add a make target to generate man pages from kernel-doc
Subsystems (3)
cover add a make target to generate man pages from kernel-doc
Currently, generation of manpages is hacky: one needs to run kernel-doc over c source files and then use an extra script to split results.
The new kernel-doc tool supports multiple files and even dirs, so there's no need to use git ls-files anymore.
Yet, it produces a single output. Change the logic to add, instead a target to docs Makefile to produce them, moving the split and build logic to sphinx-build-wrapper.
That allows honoring SPHINXDIRS when they point to a subdir, while scanning all files by default.
This series comes after:
https://lore.kernel.org/linux-doc/[email protected]/T/#t
Mauro Carvalho Chehab (1):
docs: add support to build manpages from kerneldoc output
Documentation/Makefile | 3 +- Documentation/doc-guide/kernel-doc.rst | 19 ++----- Makefile | 2 +- scripts/split-man.pl | 28 ---------- tools/docs/sphinx-build-wrapper | 77 ++++++++++++++++++++++++-- 5 files changed, 80 insertions(+), 49 deletions(-) delete mode 100755 scripts/split-man.pl
Signature · 1 line
2.51.0
PATCH 1/1 docs: add support to build manpages from kerneldoc output
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.
--- Documentation/Makefile | 3 +- Documentation/doc-guide/kernel-doc.rst | 19 ++----- Makefile | 2 +- scripts/split-man.pl | 28 ---------- tools/docs/sphinx-build-wrapper | 77 ++++++++++++++++++++++++-- 5 files changed, 80 insertions(+), 49 deletions(-) delete mode 100755 scripts/split-man.pl
Documentation/Makefile +2 -1
@@ -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'
Documentation/doc-guide/kernel-doc.rst +4 -15
@@ -579,20 +579,9 @@ 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:: +Generating man pages is a makefile target. Just 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:: - - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ - | scripts/split-man.pl /tmp/man - - $ 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``).
Makefile +1 -1
@@ -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 $@
scripts/split-man.pl deleted +0 -28
@@ -1,28 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# -# Author: Mauro Carvalho Chehab <[email protected]> -# -# Produce manpages from kernel-doc. -# See Documentation/doc-guide/kernel-doc.rst for instructions - -if ($#ARGV < 0) { - die "where do I put the results?\n"; -} - -mkdir $ARGV[0],0777; -$state = 0; -while (<STDIN>) { - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { - if ($state == 1) { close OUT } - $state = 1; - $fn = "$ARGV[0]/$1.9"; - print STDERR "Creating $fn\n"; - open OUT, ">$fn" or die "can't open $fn: $!\n"; - print OUT $_; - } elsif ($state != 0) { - print OUT $_; - } -} - -close OUT;
tools/docs/sphinx-build-wrapper +73 -4
95 lines not on this page · raw message
Signature · 1 line
2.51.0