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>
---
Documentation/Makefile | 29 +++++-----------
tools/docs/sphinx-build-wrapper | 59 ++++++++++++++++++---------------
2 files changed, 41 insertions(+), 47 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index aa42b2cb7030..b32f68387dfc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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)
@@ -67,24 +72,6 @@ pdfdocs:
@echo " SKIP Sphinx $@ target."
endif
-# 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
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 7a6eb41837e6..e24486dede76 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -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()
--
2.51.0