Re: [PATCH v8 19/24] docs: add support to build manpages from kerneldoc output

Mauro Carvalho Chehab
2025-09-29T00:44:54Z

Em Sat, 27 Sep 2025 22:35:00 +0200
Nicolas Schier <nsc@kernel.org> escreveu:

> Please note that @kernel.org receipients are still not addressed
> correctly:
>
> > Date: Thu, 18 Sep 2025 13:54:53 +0200
> > From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > To: Linux Doc Mailing List <linux-doc@vger.kernel.org>, Jonathan Corbet <corbet@lwn.net>
> > Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Akira Yokosawa <akiyks@gmail.com>,
> > 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

Just Found the issue: the problem were on a rewrite rule
on my emailer which I added ages ago. Dropped it. It should
be ok next time.

> On Thu, Sep 18, 2025 at 01:54:53PM +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 05397b9d844d..aa42b2cb7030 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::
>
> For this very patch, there is no 'scripts-build-wrapper' but
> 'sphinx-build-wrapper'. Or am I missing something?

Sorry! yes, sphinx-build-wrapper is the right name.

>
> >
> > - $ 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 $@
>
> Acked-by: Nicolas Schier <nsc@kernel.org>
Thanks!

Mauro