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@xxxxxxxxxx> escreveu:

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

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@xxxxxxxxxx>
> > ---
> >  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@xxxxxxxxxx/

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

Thanks,
Mauro