[PATCH v3 0/2] add a make target to generate man pages from kernel-doc

[PATCH v3 0/2] add a make target to generate man pages from kernel-doc

[Mauro Carvalho Chehab]

Hi Jon,

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;
- exactly one .rst file for each man page.

This is completely different than 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.
   A change like that would require adding file directory
   parameter for output, and/or teaching it about
   Documentation/output and O=;
2. make sphinx-build-wrapper do that for us. That's IMO
   the best alternative, which is what I actually implemented;
3. add a man pages Sphinx extension that would be tricking
   sphinx, making it produce one man page .rst file for each
   kernel-doc markup entry.
   This is probably doable, and could eventually bring some
   advantages, as we could also have man pages for pages 
   that are only in ReST format, but it will require some extra
   development, and likely require several changes at the
   existing .rst files. Also, generating extra output files out of
   the blue is something that Sphinx doesn't like to do, as it
   likes to have a 1:1 mapping between source files and output
   ones.
   Not sure if it worth the efforts, and will still be hackish.

I opted for (2), as it means that ones needing to generate
docs can benefit from SPHINXDIRS, and we don't need anything
extra at docs Makefile. By doing that, we can later improve the 
man pages logic without needing to touch anything else but
kernel-doc and/or the wrapper tool.

There are two points to consider:

- when SPHINXDIRS=. (the default), it searches fror all files
  treewide, even the ones without kernel-doc entries at docs,
  which is aligned with the procedure used by the current
  documentation about how to generate man pages;

- when SHINXDIRS=subdirs, it searches only for the files that
  come just after kernel-doc markups. It doesn't take into
  account any kernel-doc markup parameters to filter out
  internal/external functions or to point to an extra header
  file.

---

v3:
- fixed a badly-solved conflict on v2;
- improved documentation about manpages generation;
- added SEE ALSO at the man pages.

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

Mauro Carvalho Chehab (2):
  docs: add support to build manpages from kerneldoc output
  tools: kernel-doc: add a see also section at man pages

 Documentation/Makefile                 |  3 +-
 Documentation/doc-guide/kernel-doc.rst | 29 +++++----
 Makefile                               |  2 +-
 scripts/lib/kdoc/kdoc_files.py         |  5 +-
 scripts/lib/kdoc/kdoc_output.py        | 84 ++++++++++++++++++++++++--
 scripts/split-man.pl                   | 28 ---------
 tools/docs/sphinx-build-wrapper        | 81 +++++++++++++++++++++++--
 7 files changed, 178 insertions(+), 54 deletions(-)
 delete mode 100755 scripts/split-man.pl

-- 
2.51.0

[PATCH v3 1/2] docs: add support to build manpages from kerneldoc output

[Mauro Carvalho Chehab]

Generating man files currently requires running a separate
script. The target also doesn't appear at the docs Makefile.

Add support for mandocs at the Makefile, adding the build
logic inside sphinx-build-wrapper, updating documentation
and dropping the ancillary script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile                 |  3 +-
 Documentation/doc-guide/kernel-doc.rst | 29 ++++-----
 Makefile                               |  2 +-
 scripts/split-man.pl                   | 28 ---------
 tools/docs/sphinx-build-wrapper        | 81 ++++++++++++++++++++++++--
 5 files changed, 95 insertions(+), 48 deletions(-)
 delete mode 100755 scripts/split-man.pl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e1cb44a5fbb..22e39e5ed07d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -53,7 +53,7 @@ ifeq ($(HAVE_SPHINX),0)
 else # HAVE_SPHINX
 
 # Common documentation targets
-infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
+mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
 	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
 	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
 		--sphinxdirs="$(SPHINXDIRS)" --conf=$(SPHINX_CONF) \
@@ -104,6 +104,7 @@ dochelp:
 	@echo  '  htmldocs        - HTML'
 	@echo  '  texinfodocs     - Texinfo'
 	@echo  '  infodocs        - Info'
+	@echo  '  mandocs         - Man pages'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index af9697e60165..4370cc8fbcf5 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -579,20 +579,23 @@ source.
 How to use kernel-doc to generate man pages
 -------------------------------------------
 
-If you just want to use kernel-doc to generate man pages you can do this
-from the kernel git tree::
+To generate man pages for all files that contain kernel-doc markups, run::
 
-  $ scripts/kernel-doc -man \
-    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
-    | scripts/split-man.pl /tmp/man
+  $ make mandocs
 
-Some older versions of git do not support some of the variants of syntax for
-path exclusion.  One of the following commands may work for those versions::
+Or calling ``script-build-wrapper`` directly::
 
-  $ scripts/kernel-doc -man \
-    $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
-    | scripts/split-man.pl /tmp/man
+  $ ./tools/docs/sphinx-build-wrapper mandocs
 
-  $ scripts/kernel-doc -man \
-    $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
-    | scripts/split-man.pl /tmp/man
+The output will be at ``/man`` directory inside the output directory
+(by default: ``Documentation/output``).
+
+Optionally, it is possible to generate a partial set of man pages by
+using SPHINXDIRS:
+
+  $ make SPHINXDIRS=driver-api/media mandocs
+
+.. note::
+
+   When SPHINXDIRS={subdir} is used, it will only generate man pages for
+   the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.
diff --git a/Makefile b/Makefile
index 6bfe776bf3c5..9bd44afeda26 100644
--- a/Makefile
+++ b/Makefile
@@ -1800,7 +1800,7 @@ $(help-board-dirs): help-%:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
+	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs mandocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS):
 	$(Q)$(MAKE) $(build)=Documentation $@
diff --git a/scripts/split-man.pl b/scripts/split-man.pl
deleted file mode 100755
index 96bd99dc977a..000000000000
--- a/scripts/split-man.pl
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/usr/bin/env perl
-# SPDX-License-Identifier: GPL-2.0
-#
-# Author: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
-#
-# Produce manpages from kernel-doc.
-# See Documentation/doc-guide/kernel-doc.rst for instructions
-
-if ($#ARGV < 0) {
-   die "where do I put the results?\n";
-}
-
-mkdir $ARGV[0],0777;
-$state = 0;
-while (<STDIN>) {
-    if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
-	if ($state == 1) { close OUT }
-	$state = 1;
-	$fn = "$ARGV[0]/$1.9";
-	print STDERR "Creating $fn\n";
-	open OUT, ">$fn" or die "can't open $fn: $!\n";
-	print OUT $_;
-    } elsif ($state != 0) {
-	print OUT $_;
-    }
-}
-
-close OUT;
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index c884022ad733..932b1b675274 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -47,6 +47,7 @@ the newer version.
 import argparse
 import locale
 import os
+import re
 import shlex
 import shutil
 import subprocess
@@ -55,6 +56,7 @@ import sys
 from concurrent import futures
 
 from lib.python_version import PythonVersion
+from glob import glob
 
 LIB_DIR = "../../scripts/lib"
 SRC_DIR = os.path.dirname(os.path.realpath(__file__))
@@ -77,6 +79,7 @@ TARGETS = {
     "epubdocs":      { "builder": "epub",    "out_dir": "epub" },
     "texinfodocs":   { "builder": "texinfo", "out_dir": "texinfo" },
     "infodocs":      { "builder": "texinfo", "out_dir": "texinfo" },
+    "mandocs":       { "builder": "man",     "out_dir": "man" },
     "latexdocs":     { "builder": "latex",   "out_dir": "latex" },
     "pdfdocs":       { "builder": "latex",   "out_dir": "latex" },
     "xmldocs":       { "builder": "xml",     "out_dir": "xml" },
@@ -455,6 +458,71 @@ class SphinxBuilder:
             except subprocess.CalledProcessError as e:
                 sys.exit(f"Error generating info docs: {e}")
 
+    def handle_man(self, kerneldoc, docs_dir, src_dir, output_dir):
+        """
+        Create man pages from kernel-doc output
+        """
+
+        re_kernel_doc = re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)")
+        re_man = re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"')
+
+        if docs_dir == src_dir:
+            #
+            # Pick the entire set of kernel-doc markups from the entire tree
+            #
+            kdoc_files = set([self.srctree])
+        else:
+            kdoc_files = set()
+
+            for fname in glob(os.path.join(src_dir, "**"), recursive=True):
+                if os.path.isfile(fname) and fname.endswith(".rst"):
+                    with open(fname, "r", encoding="utf-8") as in_fp:
+                        data = in_fp.read()
+
+                    for line in data.split("\n"):
+                        match = re_kernel_doc.match(line)
+                        if match:
+                            if os.path.isfile(match.group(1)):
+                                kdoc_files.add(match.group(1))
+
+        if not kdoc_files:
+                sys.exit(f"Directory {src_dir} doesn't contain kernel-doc tags")
+
+        cmd = [ kerneldoc, "-m" ] + sorted(kdoc_files)
+        try:
+            if self.verbose:
+                print(" ".join(cmd))
+
+            result = subprocess.run(cmd, stdout=subprocess.PIPE, text= True)
+
+            if result.returncode:
+                print(f"Warning: kernel-doc returned {result.returncode} warnings")
+
+        except (OSError, ValueError, subprocess.SubprocessError) as e:
+            sys.exit(f"Failed to create man pages for {src_dir}: {repr(e)}")
+
+        fp = None
+        try:
+            for line in result.stdout.split("\n"):
+                match = re_man.match(line)
+                if not match:
+                    if fp:
+                        fp.write(line + '\n')
+                    continue
+
+                if fp:
+                    fp.close()
+
+                fname = f"{output_dir}/{match.group(2)}.{match.group(1)}"
+
+                if self.verbose:
+                    print(f"Creating {fname}")
+                fp = open(fname, "w", encoding="utf-8")
+                fp.write(line + '\n')
+        finally:
+            if fp:
+                fp.close()
+
     def cleandocs(self, builder):           # pylint: disable=W0613
         """Remove documentation output directory"""
         shutil.rmtree(self.builddir, ignore_errors=True)
@@ -483,7 +551,7 @@ class SphinxBuilder:
         # Other targets require sphinx-build, so check if it exists
         #
         sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"])
-        if not sphinxbuild:
+        if not sphinxbuild and target != "mandocs":
             sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n")
 
         if builder == "latex":
@@ -572,10 +640,13 @@ class SphinxBuilder:
                 output_dir,
             ]
 
-            try:
-                self.run_sphinx(sphinxbuild, build_args, env=self.env)
-            except (OSError, ValueError, subprocess.SubprocessError) as e:
-                sys.exit(f"Build failed: {repr(e)}")
+            if target == "mandocs":
+                self.handle_man(kerneldoc, docs_dir, src_dir, output_dir)
+            else:
+                try:
+                    self.run_sphinx(sphinxbuild, build_args, env=self.env)
+                except (OSError, ValueError, subprocess.SubprocessError) as e:
+                    sys.exit(f"Build failed: {repr(e)}")
 
             #
             # Ensure that each html/epub output will have needed static files
-- 
2.51.0

[PATCH v3 2/2] tools: kernel-doc: add a see also section at man pages

[Mauro Carvalho Chehab]

While cross-references are complex, as related ones can be on
different files, we can at least correlate the ones that belong
to the same file, adding a SEE ALSO section for them.

The result is not bad. See for instance:

	$ tools/docs/sphinx-build-wrapper --sphinxdirs driver-api/media -- mandocs
	$ man Documentation/output/driver-api/man/edac_pci_add_device.9

	edac_pci_add_device(9)  Kernel Hacker's Manual  edac_pci_add_device(9)

	NAME
	       edac_pci_add_device  - Insert the 'edac_dev' structure into the
	       edac_pci global list and create sysfs entries  associated  with
	       edac_pci structure.

	SYNOPSIS
	       int  edac_pci_add_device  (struct  edac_pci_ctl_info *pci , int
	       edac_idx );

	ARGUMENTS
	       pci         pointer to the edac_device structure to be added to
	                   the list

	       edac_idx    A unique numeric identifier to be assigned to the

	RETURN
	       0 on Success, or an error code on failure

	SEE ALSO
	       edac_pci_alloc_ctl_info(9),          edac_pci_free_ctl_info(9),
	       edac_pci_alloc_index(9),  edac_pci_del_device(9), edac_pci_cre‐
	       ate_generic_ctl(9),            edac_pci_release_generic_ctl(9),
	       edac_pci_create_sysfs(9), edac_pci_remove_sysfs(9)

	August 2025               edac_pci_add_device   edac_pci_add_device(9)

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/lib/kdoc/kdoc_files.py  |  5 +-
 scripts/lib/kdoc/kdoc_output.py | 84 +++++++++++++++++++++++++++++++--
 2 files changed, 83 insertions(+), 6 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py
index 9e09b45b02fa..061c033f32da 100644
--- a/scripts/lib/kdoc/kdoc_files.py
+++ b/scripts/lib/kdoc/kdoc_files.py
@@ -275,7 +275,10 @@ class KernelFiles():
                 self.config.log.warning("No kernel-doc for file %s", fname)
                 continue
 
-            for arg in self.results[fname]:
+            symbols = self.results[fname]
+            self.out_style.set_symbols(symbols)
+
+            for arg in symbols:
                 m = self.out_msg(fname, arg.name, arg)
 
                 if m is None:
diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index ea8914537ba0..1eca9a918558 100644
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -215,6 +215,9 @@ class OutputFormat:
 
     # Virtual methods to be overridden by inherited classes
     # At the base class, those do nothing.
+    def set_symbols(self, symbols):
+        """Get a list of all symbols from kernel_doc"""
+
     def out_doc(self, fname, name, args):
         """Outputs a DOC block"""
 
@@ -577,6 +580,7 @@ class ManFormat(OutputFormat):
 
         super().__init__()
         self.modulename = modulename
+        self.symbols = []
 
         dt = None
         tstamp = os.environ.get("KBUILD_BUILD_TIMESTAMP")
@@ -593,6 +597,68 @@ class ManFormat(OutputFormat):
 
         self.man_date = dt.strftime("%B %Y")
 
+    def arg_name(self, args, name):
+        """
+        Return the name that will be used for the man page.
+
+        As we may have the same name on different namespaces,
+        prepend the data type for all types except functions and typedefs.
+
+        The doc section is special: it uses the modulename.
+        """
+
+        dtype = args.type
+
+        if dtype == "doc":
+            return self.modulename
+
+        if dtype in ["function", "typedef"]:
+            return name
+
+        return f"{dtype} {name}"
+
+    def set_symbols(self, symbols):
+        """
+        Get a list of all symbols from kernel_doc.
+
+        Man pages will uses it to add a SEE ALSO section with other
+        symbols at the same file.
+        """
+        self.symbols = symbols
+
+    def out_tail(self, fname, name, args):
+        """Adds a tail for all man pages"""
+
+        # SEE ALSO section
+        if len(self.symbols) >= 2:
+            cur_name = self.arg_name(args, name)
+
+            self.data += f'.SH "SEE ALSO"' + "\n.PP\n"
+            related = []
+            for arg in self.symbols:
+                out_name = self.arg_name(arg, arg.name)
+
+                if cur_name == out_name:
+                    continue
+
+                related.append(f"\\fB{out_name}\\fR(9)")
+
+            self.data += ",\n".join(related) + "\n"
+
+        # TODO: does it make sense to add other sections? Maybe
+        # REPORTING ISSUES? LICENSE?
+
+    def msg(self, fname, name, args):
+        """
+        Handles a single entry from kernel-doc parser.
+
+        Add a tail at the end of man pages output.
+        """
+        super().msg(fname, name, args)
+        self.out_tail(fname, name, args)
+
+        return self.data
+
     def output_highlight(self, block):
         """
         Outputs a C symbol that may require being highlighted with
@@ -618,7 +684,9 @@ class ManFormat(OutputFormat):
         if not self.check_doc(name, args):
             return
 
-        self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n"
+        out_name = self.arg_name(args, name)
+
+        self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
 
         for section, text in args.sections.items():
             self.data += f'.SH "{section}"' + "\n"
@@ -627,7 +695,9 @@ class ManFormat(OutputFormat):
     def out_function(self, fname, name, args):
         """output function in man"""
 
-        self.data += f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
+        out_name = self.arg_name(args, name)
+
+        self.data += f'.TH "{name}" 9 "{out_name}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
 
         self.data += ".SH NAME\n"
         self.data += f"{name} \\- {args['purpose']}\n"
@@ -671,7 +741,9 @@ class ManFormat(OutputFormat):
             self.output_highlight(text)
 
     def out_enum(self, fname, name, args):
-        self.data += f'.TH "{self.modulename}" 9 "enum {name}" "{self.man_date}" "API Manual" LINUX' + "\n"
+        out_name = self.arg_name(args, name)
+
+        self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
 
         self.data += ".SH NAME\n"
         self.data += f"enum {name} \\- {args['purpose']}\n"
@@ -703,8 +775,9 @@ class ManFormat(OutputFormat):
     def out_typedef(self, fname, name, args):
         module = self.modulename
         purpose = args.get('purpose')
+        out_name = self.arg_name(args, name)
 
-        self.data += f'.TH "{module}" 9 "{name}" "{self.man_date}" "API Manual" LINUX' + "\n"
+        self.data += f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
 
         self.data += ".SH NAME\n"
         self.data += f"typedef {name} \\- {purpose}\n"
@@ -717,8 +790,9 @@ class ManFormat(OutputFormat):
         module = self.modulename
         purpose = args.get('purpose')
         definition = args.get('definition')
+        out_name = self.arg_name(args, name)
 
-        self.data += f'.TH "{module}" 9 "{args.type} {name}" "{self.man_date}" "API Manual" LINUX' + "\n"
+        self.data += f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
 
         self.data += ".SH NAME\n"
         self.data += f"{args.type} {name} \\- {purpose}\n"
-- 
2.51.0

Re: [PATCH v3 1/2] docs: add support to build manpages from kerneldoc output

[Nicolas Schier]

Please check your mail tooling: something strange happened to all
@kernel.org adresses:

> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
>         Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
>         Thomas Weißschuh <thomas.weissschuh@linutronix.de>,
>         Alice Ryhl <aliceryhl@google.com>,
>         Masahiro Yamada <mchehab+huawei@kernel.org>,
>         Miguel Ojeda <mchehab+huawei@kernel.org>,
>         Nathan Chancellor <mchehab+huawei@kernel.org>,
>         Nicolas Schier <nicolas.schier@linux.dev>,
>         Randy Dunlap <rdunlap@infradead.org>,
>         Tamir Duberstein <tamird@gmail.com>,
>         linux-kbuild@vger.kernel.org,
>         linux-kernel@vger.kernel.org

On Wed, Aug 27, 2025 at 10:26:37AM +0200, Mauro Carvalho Chehab wrote:
> Generating man files currently requires running a separate
> script. The target also doesn't appear at the docs Makefile.
> 
> Add support for mandocs at the Makefile, adding the build
> logic inside sphinx-build-wrapper, updating documentation
> and dropping the ancillary script.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/Makefile                 |  3 +-
>  Documentation/doc-guide/kernel-doc.rst | 29 ++++-----
>  Makefile                               |  2 +-
>  scripts/split-man.pl                   | 28 ---------
>  tools/docs/sphinx-build-wrapper        | 81 ++++++++++++++++++++++++--
>  5 files changed, 95 insertions(+), 48 deletions(-)
>  delete mode 100755 scripts/split-man.pl
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 3e1cb44a5fbb..22e39e5ed07d 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -53,7 +53,7 @@ ifeq ($(HAVE_SPHINX),0)
>  else # HAVE_SPHINX
>  
>  # Common documentation targets
> -infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> +mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
>  	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
>  	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
>  		--sphinxdirs="$(SPHINXDIRS)" --conf=$(SPHINX_CONF) \
> @@ -104,6 +104,7 @@ dochelp:
>  	@echo  '  htmldocs        - HTML'
>  	@echo  '  texinfodocs     - Texinfo'
>  	@echo  '  infodocs        - Info'
> +	@echo  '  mandocs         - Man pages'
>  	@echo  '  latexdocs       - LaTeX'
>  	@echo  '  pdfdocs         - PDF'
>  	@echo  '  epubdocs        - EPUB'
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index af9697e60165..4370cc8fbcf5 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -579,20 +579,23 @@ source.
>  How to use kernel-doc to generate man pages
>  -------------------------------------------
>  
> -If you just want to use kernel-doc to generate man pages you can do this
> -from the kernel git tree::
> +To generate man pages for all files that contain kernel-doc markups, run::
>  
> -  $ scripts/kernel-doc -man \
> -    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> -    | scripts/split-man.pl /tmp/man
> +  $ make mandocs
>  
> -Some older versions of git do not support some of the variants of syntax for
> -path exclusion.  One of the following commands may work for those versions::
> +Or calling ``script-build-wrapper`` directly::

                ^^^^^^ sphinx-build-wrapper ?

Kind regards
Nicolas

Re: [PATCH v3 1/2] docs: add support to build manpages from kerneldoc output

[Mauro Carvalho Chehab]

Em Thu, 28 Aug 2025 00:04:08 +0200
Nicolas Schier <nsc@kernel.org> escreveu:

> Please check your mail tooling: something strange happened to all
> @kernel.org adresses:
> 
> > Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
> >         Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
> >         Thomas Weißschuh <thomas.weissschuh@linutronix.de>,
> >         Alice Ryhl <aliceryhl@google.com>,
> >         Masahiro Yamada <mchehab+huawei@kernel.org>,
> >         Miguel Ojeda <mchehab+huawei@kernel.org>,
> >         Nathan Chancellor <mchehab+huawei@kernel.org>,
> >         Nicolas Schier <nicolas.schier@linux.dev>,
> >         Randy Dunlap <rdunlap@infradead.org>,
> >         Tamir Duberstein <tamird@gmail.com>,
> >         linux-kbuild@vger.kernel.org,
> >         linux-kernel@vger.kernel.org  

That's really weird! Thanks for letting me know. It was not supposed
to do any e-mail changes.

> 
> On Wed, Aug 27, 2025 at 10:26:37AM +0200, Mauro Carvalho Chehab wrote:
> > Generating man files currently requires running a separate
> > script. The target also doesn't appear at the docs Makefile.
> > 
> > Add support for mandocs at the Makefile, adding the build
> > logic inside sphinx-build-wrapper, updating documentation
> > and dropping the ancillary script.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/Makefile                 |  3 +-
> >  Documentation/doc-guide/kernel-doc.rst | 29 ++++-----
> >  Makefile                               |  2 +-
> >  scripts/split-man.pl                   | 28 ---------
> >  tools/docs/sphinx-build-wrapper        | 81 ++++++++++++++++++++++++--
> >  5 files changed, 95 insertions(+), 48 deletions(-)
> >  delete mode 100755 scripts/split-man.pl
> > 
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 3e1cb44a5fbb..22e39e5ed07d 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -53,7 +53,7 @@ ifeq ($(HAVE_SPHINX),0)
> >  else # HAVE_SPHINX
> >  
> >  # Common documentation targets
> > -infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> > +mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
> >  	$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
> >  	+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
> >  		--sphinxdirs="$(SPHINXDIRS)" --conf=$(SPHINX_CONF) \
> > @@ -104,6 +104,7 @@ dochelp:
> >  	@echo  '  htmldocs        - HTML'
> >  	@echo  '  texinfodocs     - Texinfo'
> >  	@echo  '  infodocs        - Info'
> > +	@echo  '  mandocs         - Man pages'
> >  	@echo  '  latexdocs       - LaTeX'
> >  	@echo  '  pdfdocs         - PDF'
> >  	@echo  '  epubdocs        - EPUB'
> > diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> > index af9697e60165..4370cc8fbcf5 100644
> > --- a/Documentation/doc-guide/kernel-doc.rst
> > +++ b/Documentation/doc-guide/kernel-doc.rst
> > @@ -579,20 +579,23 @@ source.
> >  How to use kernel-doc to generate man pages
> >  -------------------------------------------
> >  
> > -If you just want to use kernel-doc to generate man pages you can do this
> > -from the kernel git tree::
> > +To generate man pages for all files that contain kernel-doc markups, run::
> >  
> > -  $ scripts/kernel-doc -man \
> > -    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> > -    | scripts/split-man.pl /tmp/man
> > +  $ make mandocs
> >  
> > -Some older versions of git do not support some of the variants of syntax for
> > -path exclusion.  One of the following commands may work for those versions::
> > +Or calling ``script-build-wrapper`` directly::  
> 
>                 ^^^^^^ sphinx-build-wrapper ?

This is on a separate patch series:

https://lore.kernel.org/linux-doc/cover.1756138805.git.mchehab+huawei@kernel.org/

It basically moves the complex logic around docs Makefile into a
script that can either be called via Makefile or directly.

Thanks,
Mauro