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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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