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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <aK-A2DmxhGDQGVEf@levanger>
Date: Thu, 28 Aug 2025 00:04:08 +0200
From: Nicolas Schier <nsc@...nel.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
	Jonathan Corbet <corbet@....net>,
	Thomas Weißschuh <thomas.weissschuh@...utronix.de>,
	Alice Ryhl <aliceryhl@...gle.com>,
	Randy Dunlap <rdunlap@...radead.org>,
	Tamir Duberstein <tamird@...il.com>, linux-kbuild@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 1/2] docs: add support to build manpages from
 kerneldoc output

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

> Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
>         Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
>         Thomas Weißschuh <thomas.weissschuh@...utronix.de>,
>         Alice Ryhl <aliceryhl@...gle.com>,
>         Masahiro Yamada <mchehab+huawei@...nel.org>,
>         Miguel Ojeda <mchehab+huawei@...nel.org>,
>         Nathan Chancellor <mchehab+huawei@...nel.org>,
>         Nicolas Schier <nicolas.schier@...ux.dev>,
>         Randy Dunlap <rdunlap@...radead.org>,
>         Tamir Duberstein <tamird@...il.com>,
>         linux-kbuild@...r.kernel.org,
>         linux-kernel@...r.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@...nel.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