Message-ID: <cover.1756222182.git.mchehab+huawei@kernel.org>
Date: Tue, 26 Aug 2025 17:49:01 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	linux-kernel@...r.kernel.org,
	Jonathan Corbet <corbet@....net>,
	linux-kbuild@...r.kernel.org
Subject: [PATCH v2 0/1] add a make target to generate man pages from kernel-doc

Hi Jon,

Please ingore the first version. It was done on the top of a past
implementation. That's the right one ;-)

Currently, generation of manpages is hacky: one needs to run
kernel-doc over c source files and then use an extra script to
split results.

The new kernel-doc tool supports multiple files and even dirs,
so there's no need to use git ls-files anymore.

Yet, it produces a single output. Change the logic to add, instead
a target to docs Makefile to produce them, moving the split
and build logic to sphinx-build-wrapper.

That allows honoring SPHINXDIRS when they point to a subdir,
while scanning all files by default.

This series comes after:
    https://lore.kernel.org/linux-doc/cover.1756138805.git.mchehab+huawei@kernel.org/T/#t

-

It should be noticed that, while Sphinx does have a man pages
builder, it requires a completely different set of ReST entries
that would need to be designed specially for that:

- for each man page, an entry at conf.py is required;
- the ReST page should be in a format closer to a real man page.

This is completely different from the approach we take where
we have, where kernel-doc direcly generates groff output
formated data.

So, yeah, this is still a little bit hackish, but to avoid
that we would need a completely different setup with, frankly,
would be a headache to setup and maintain.

With that in mind, there are a couple of possible alternatives:

1. change kernel-doc to produce one file per man page;
2. make sphinx-build-wrapper do that for us;
3. have a man pages Sphinx extension that would be filling
   man_pages and calling kernel-doc in the background.

(3) is probably doable, and could eventually bring some
    advantages, as we could have man pages for pages that
    are only in ReST format, but it will require some extra
    development. Not sure if it worth the efforts.

I opted for (2), as it means that ones needing to generate
docs can benefit from SPHINXDIRS. By doing that, we can later
improve the man pages logic without needing to touch anything
else.

There are two points to consider:

- when SPHINXDIRS=. (the default), it searches fror all files
  treewide, which is aligned with the procedure defined at the
  current documentation;

- when SHINXDIRS=subdirs, it searches only for the files that
  come just after kernel-doc, excluding the files and filter
  logic that could be just at the at the kernel-doc options.

---

v2:
- no actual changes, but it was rebased on the top of the actual
  pacth series, in order to apply cleanly.

Mauro Carvalho Chehab (1):
  docs: add support to build manpages from kerneldoc output

 Documentation/Makefile                 |  3 +-
 Documentation/doc-guide/kernel-doc.rst | 19 ++-----
 Makefile                               |  2 +-
 scripts/split-man.pl                   | 28 ---------
 tools/docs/sphinx-build-wrapper        | 78 ++++++++++++++++++++++++--
 5 files changed, 81 insertions(+), 49 deletions(-)
 delete mode 100755 scripts/split-man.pl

-- 
2.51.0

Powered by blists - more mailing lists