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

[Nicolas Schier <nsc@kernel.org>]

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


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?

>  
> -  $ 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>