| 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
| ||
|
Message-ID: <aNhKdCrSM29uwvpn@levanger>
Date: Sat, 27 Sep 2025 22:35:00 +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>, Akira Yokosawa <akiyks@...il.com>,
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 v8 19/24] docs: add support to build manpages from
kerneldoc output
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@...nel.org>
> To: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Jonathan Corbet <corbet@....net>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Akira Yokosawa <akiyks@...il.com>,
> 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 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@...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 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@...nel.org>
Powered by blists - more mailing lists