torvalds/linux
3
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-03-22 07:27:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add support to build manpages from kerneldoc output

Browse Source 
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>
Message-ID: <3d248d724e7f3154f6e3a227e5923d7360201de9.1758196090.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
2025-09-18 13:54:53 +02:00
committed by Jonathan Corbet
parent 0d9abc7627
commit 7e8a8143ec
5 changed files with 98 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
tools/docs/sphinx-build-wrapper
View File

@@ -47,12 +47,14 @@ the newer version.
import argparse
import locale
import os
import re
import shlex
import shutil
import subprocess
import sys
from concurrent import futures
from glob import glob
from lib.python_version import PythonVersion
from lib.latex_fonts import LatexFontChecker
@@ -77,6 +79,7 @@ TARGETS = {
"epubdocs": { "builder": "epub", "out_dir": "epub" },
"texinfodocs": { "builder": "texinfo", "out_dir": "texinfo" },
"infodocs": { "builder": "texinfo", "out_dir": "texinfo" },
"mandocs": { "builder": "man", "out_dir": "man" },
"latexdocs": { "builder": "latex", "out_dir": "latex" },
"pdfdocs": { "builder": "latex", "out_dir": "latex" },
"xmldocs": { "builder": "xml", "out_dir": "xml" },
@@ -503,6 +506,71 @@ class SphinxBuilder:
except subprocess.CalledProcessError as e:
sys.exit(f"Error generating info docs: {e}")
def handle_man(self, kerneldoc, docs_dir, src_dir, output_dir):
"""
Create man pages from kernel-doc output
"""
re_kernel_doc = re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)")
re_man = re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"')
if docs_dir == src_dir:
#
# Pick the entire set of kernel-doc markups from the entire tree
#
kdoc_files = set([self.srctree])
else:
kdoc_files = set()
for fname in glob(os.path.join(src_dir, "**"), recursive=True):
if os.path.isfile(fname) and fname.endswith(".rst"):
with open(fname, "r", encoding="utf-8") as in_fp:
data = in_fp.read()
for line in data.split("\n"):
match = re_kernel_doc.match(line)
if match:
if os.path.isfile(match.group(1)):
kdoc_files.add(match.group(1))
if not kdoc_files:
sys.exit(f"Directory {src_dir} doesn't contain kernel-doc tags")
cmd = [ kerneldoc, "-m" ] + sorted(kdoc_files)
try:
if self.verbose:
print(" ".join(cmd))
result = subprocess.run(cmd, stdout=subprocess.PIPE, text= True)
if result.returncode:
print(f"Warning: kernel-doc returned {result.returncode} warnings")
except (OSError, ValueError, subprocess.SubprocessError) as e:
sys.exit(f"Failed to create man pages for {src_dir}: {repr(e)}")
fp = None
try:
for line in result.stdout.split("\n"):
match = re_man.match(line)
if not match:
if fp:
fp.write(line + '\n')
continue
if fp:
fp.close()
fname = f"{output_dir}/{match.group(2)}.{match.group(1)}"
if self.verbose:
print(f"Creating {fname}")
fp = open(fname, "w", encoding="utf-8")
fp.write(line + '\n')
finally:
if fp:
fp.close()
def cleandocs(self, builder): # pylint: disable=W0613
"""Remove documentation output directory"""
shutil.rmtree(self.builddir, ignore_errors=True)
@@ -531,7 +599,7 @@ class SphinxBuilder:
# Other targets require sphinx-build, so check if it exists
#
sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"])
if not sphinxbuild:
if not sphinxbuild and target != "mandocs":
sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n")
if builder == "latex":
@@ -619,10 +687,13 @@ class SphinxBuilder:
output_dir,
]
try:
self.run_sphinx(sphinxbuild, build_args, env=self.env)
except (OSError, ValueError, subprocess.SubprocessError) as e:
sys.exit(f"Build failed: {repr(e)}")
if target == "mandocs":
self.handle_man(kerneldoc, docs_dir, src_dir, output_dir)
else:
try:
self.run_sphinx(sphinxbuild, build_args, env=self.env)
except (OSError, ValueError, subprocess.SubprocessError) as e:
sys.exit(f"Build failed: {repr(e)}")
#
# Ensure that each html/epub output will have needed static files