admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

tools/docs: sphinx-build-wrapper: move rust doc builder to wrapper

Browse Source 
Simplify even further the docs Makefile by moving rust build logic
to the wrapper.

After this change, running make on an environment with rust enabled
works as expected.

With CONFIG_RUST:

    $ make O=/tmp/foo LLVM=1 SPHINXDIRS=peci htmldocs
    make[1]: Entrando no diretório '/tmp/foo'

    Using alabaster theme
    Using Python kernel-doc
      GEN     Makefile
      DESCEND objtool
      CC      arch/x86/kernel/asm-offsets.s
      INSTALL libsubcmd_headers
      CALL    /new_devel/docs/scripts/checksyscalls.sh
      RUSTC L rust/core.o
      BINDGEN rust/bindings/bindings_generated.rs
      BINDGEN rust/bindings/bindings_helpers_generated.rs
    ...

Without it:
    $ make SPHINXDIRS=peci htmldocs
    Using alabaster theme
    Using Python kernel-doc

Both work as it is it is supposed to do.

After the change, it is also possible to build directly with the script
by passing "--rustodoc".

if CONFIG_RUST, this works fine:

    $ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs
    Using alabaster theme
    Using Python kernel-doc
      SYNC    include/config/auto.conf
    ...
      RUSTC L rust/core.o
    ...

If not, it will produce a warning that RUST may be disabled:

    $ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs
    Using alabaster theme
    Using Python kernel-doc
    ***
    *** Configuration file ".config" not found!
    ***
    *** Please run some configurator (e.g. "make oldconfig" or
    *** "make menuconfig" or "make xconfig").
    ***
    make[1]: *** [/new_devel/docs/Makefile:829: .config] Error 1
    make: *** [Makefile:248: __sub-make] Error 2
    Ignored errors when building rustdoc: Command '['make', 'LLVM=1', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <fa1235ccf859f6ebfeef7ffba0ebde2015a75042.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:56 +02:00
committed by Jonathan Corbet
parent ade9b9576e
commit 2118ba7da6
2 changed files with 41 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Documentation/Makefile
View File

@@ -23,6 +23,7 @@ SPHINXOPTS =
SPHINXDIRS = .
DOCS_THEME =
DOCS_CSS =
RUSTDOC =
SPHINX_CONF = conf.py
PAPER =
BUILDDIR = $(obj)/output
@@ -42,6 +43,10 @@ FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
# User-friendly check for sphinx-build
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
ifeq ($(CONFIG_RUST),y)
RUSTDOC="--rustdoc"
endif
ifeq ($(HAVE_SPHINX),0)
.DEFAULT:
@@ -53,10 +58,10 @@ ifeq ($(HAVE_SPHINX),0)
else # HAVE_SPHINX
# Common documentation targets
mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
htmldocs 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)" \
+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ $(RUSTDOC)\
--sphinxdirs="$(SPHINXDIRS)" --conf="$(SPHINX_CONF)" $(RUSTDOC)\
--builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
--theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
@@ -69,25 +74,6 @@ endif
htmldocs-redirects: $(srctree)/Documentation/.renames.txt
@tools/docs/gen-redirects.py --output $(BUILDDIR) < $<
# HTML main logic is identical to other targets. However, if rust is enabled,
# an extra step at the end is required to generate rustdoc.
htmldocs:
$(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check
+$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \
--sphinxdirs="$(SPHINXDIRS)" --conf="$(SPHINX_CONF)" \
--builddir="$(BUILDDIR)" \
--theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
# If Rust support is available and .config exists, add rustdoc generated contents.
# If there are any, the errors from this make rustdoc will be displayed but
# won't stop the execution of htmldocs
ifneq ($(wildcard $(srctree)/.config),)
ifeq ($(CONFIG_RUST),y)
$(Q)$(MAKE) rustdoc || true
endif
endif
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should

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

@@ -96,14 +96,6 @@ class SphinxBuilder:
with the Kernel.
"""
def is_rust_enabled(self):
"""Check if rust is enabled at .config"""
config_path = os.path.join(self.srctree, ".config")
if os.path.isfile(config_path):
with open(config_path, "r", encoding="utf-8") as f:
return "CONFIG_RUST=y" in f.read()
return False
def get_path(self, path, use_cwd=False, abs_path=False):
"""
Ancillary routine to handle patches the right way, as shell does.
@@ -218,8 +210,6 @@ class SphinxBuilder:
"scripts/kernel-doc.py"))
self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
self.config_rust = self.is_rust_enabled()
#
# Get directory locations for LaTeX build toolchain
#
@@ -274,7 +264,7 @@ class SphinxBuilder:
return subprocess.call(cmd, *args, **pwargs)
def handle_html(self, css, output_dir):
def handle_html(self, css, output_dir, rustdoc):
"""
Extra steps for HTML and epub output.
@@ -282,20 +272,34 @@ class SphinxBuilder:
copied to the output _static directory
"""
if not css:
return
if css:
css = os.path.expanduser(css)
if not css.startswith("/"):
css = os.path.join(self.srctree, css)
css = os.path.expanduser(css)
if not css.startswith("/"):
css = os.path.join(self.srctree, css)
static_dir = os.path.join(output_dir, "_static")
os.makedirs(static_dir, exist_ok=True)
static_dir = os.path.join(output_dir, "_static")
os.makedirs(static_dir, exist_ok=True)
try:
shutil.copy2(css, static_dir)
except (OSError, IOError) as e:
print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr)
try:
shutil.copy2(css, static_dir)
except (OSError, IOError) as e:
print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr)
if rustdoc:
if "MAKE" in self.env:
cmd = [self.env["MAKE"]]
else:
cmd = ["make", "LLVM=1"]
cmd += [ "rustdoc"]
if self.verbose:
print(" ".join(cmd))
try:
subprocess.run(cmd, check=True)
except subprocess.CalledProcessError as e:
print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?",
file=sys.stderr)
def build_pdf_file(self, latex_cmd, from_dir, path):
"""Builds a single pdf file using latex_cmd"""
@@ -576,7 +580,7 @@ class SphinxBuilder:
shutil.rmtree(self.builddir, ignore_errors=True)
def build(self, target, sphinxdirs=None, conf="conf.py",
theme=None, css=None, paper=None, deny_vf=None):
theme=None, css=None, paper=None, deny_vf=None, rustdoc=False):
"""
Build documentation using Sphinx. This is the core function of this
module. It prepares all arguments required by sphinx-build.
@@ -623,7 +627,7 @@ class SphinxBuilder:
args.extend(["-D", f"latex_elements.papersize={paper}paper"])
if self.config_rust:
if rustdoc:
args.extend(["-t", "rustdoc"])
if conf:
@@ -699,7 +703,7 @@ class SphinxBuilder:
# Ensure that each html/epub output will have needed static files
#
if target in ["htmldocs", "epubdocs"]:
self.handle_html(css, output_dir)
self.handle_html(css, output_dir, rustdoc)
#
# Step 2: Some targets (PDF and info) require an extra step once
@@ -756,6 +760,9 @@ def main():
parser.add_argument('--deny-vf',
help="Configuration to deny variable fonts on pdf builds")
parser.add_argument('--rustdoc', action="store_true",
help="Enable rustdoc build. Requires CONFIG_RUST")
parser.add_argument("-v", "--verbose", action='store_true',
help="place build in verbose mode")
@@ -775,7 +782,7 @@ def main():
builder.build(args.target, sphinxdirs=args.sphinxdirs, conf=args.conf,
theme=args.theme, css=args.css, paper=args.paper,
deny_vf=args.deny_vf)
rustdoc=args.rustdoc, deny_vf=args.deny_vf)
if __name__ == "__main__":
main()