From nobody Thu Oct 2 13:07:13 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C94DC31A814; Wed, 17 Sep 2025 12:15:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1758111355; cv=none; b=o3HqGdFpto+faHg2vPz1esloirWXkmyVpmIgf8KDVfZmLam5DTKFnDY9E+zAsxnGUo77UqeREcYYz8VWlj2Ca5l1/ULSfVnjfg2CJk2xTqDGE1G2qDIEG/1KYlMsAUNtWHZqw/tLu90ZLAtnC33C50ypmYslSCQJ2NJCCi1IEmU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1758111355; c=relaxed/simple; bh=lrdZawkRIwStzU2yfc2G77xAk+2MIGzDv7SZmR0L4QE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=RaTvxys1BOFkCEM2+hrISJWJd5ucEkChilbjaMOoMnTkLeFid89fvpQw8G+E8/+erxMwPe6WWXWECeYqBSfNNpv/fbcfEJdu18e40a+rLsBPhj769luD31bz6S69SsYbpRaVOFQXLFQZauX5wZa4GmjE+5S0c742TSWbbxcZoAc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=lBrbbbIS; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="lBrbbbIS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3ED8FC4AF0B; Wed, 17 Sep 2025 12:15:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1758111355; bh=lrdZawkRIwStzU2yfc2G77xAk+2MIGzDv7SZmR0L4QE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lBrbbbIScd0kAq84yYc3uTrivnTKTe4chMBtWl1x7zkjAEyU1OTe5QsgRXtHn598Z 1Wgm+gT/bQdwkKdgNpPIDf0LfGqYzDKmsq4BHqvRJ8HmlB6EQXZfgxoGUiZyWGLldR ZjvfA+jloScArCXlAG4OQ8aHVLuE6wmv2/zwRERwjTROceLA4knbwRP+pNiAHAb5Vx WH8hNMneGwlzwxlE9gBcPAdrf/E4lNc23WaahnoMaMvWVXDxkLUEIQqiv85HSxyW9W /KNJYh7u7VlR97dG5gUE6P8aOYUkU4xEvpZJK/3/5B4F0fSO1T01qLGEv4DlEyC1/C 1UlBs6GWoyCCw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uyr4h-0000000CGea-2ezA; Wed, 17 Sep 2025 14:15:51 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , "Mauro Carvalho Chehab" , Alex Gaynor , Alice Ryhl , Andreas Hindborg , Benno Lossin , Bill Wendling , Boqun Feng , Danilo Krummrich , Gary Guo , Justin Stitt , Miguel Ojeda , Nathan Chancellor , Nick Desaulniers , Trevor Gross , linux-kernel@vger.kernel.org, llvm@lists.linux.dev, rust-for-linux@vger.kernel.org Subject: [PATCH v7 22/24] tools/docs: sphinx-build-wrapper: move rust doc builder to wrapper Date: Wed, 17 Sep 2025 14:15:16 +0200 Message-ID: <6794e21fda3158c1d7d385a2e61df2354d42ce54.1758111077.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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=3D/tmp/foo LLVM=3D1 SPHINXDIRS=3Dpeci htmldocs make[1]: Entrando no diret=C3=B3rio '/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=3Dpeci 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 -- html= docs 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 -- html= docs 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=3D1', 'ru= stdoc']' returned non-zero exit status 2.. Is RUST enabled? Signed-off-by: Mauro Carvalho Chehab --- 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 =3D SPHINXDIRS =3D . DOCS_THEME =3D DOCS_CSS =3D +RUSTDOC =3D SPHINX_CONF =3D conf.py PAPER =3D BUILDDIR =3D $(obj)/output @@ -42,6 +43,10 @@ FONTS_CONF_DENY_VF ?=3D $(HOME)/deny-vf # User-friendly check for sphinx-build HAVE_SPHINX :=3D $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then ech= o 1; else echo 0; fi) =20 +ifeq ($(CONFIG_RUST),y) + RUSTDOC=3D"--rustdoc" +endif + ifeq ($(HAVE_SPHINX),0) =20 .DEFAULT: @@ -53,10 +58,10 @@ ifeq ($(HAVE_SPHINX),0) else # HAVE_SPHINX =20 # Common documentation targets -mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckd= ocs: +htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs l= inkcheckdocs: $(Q)@$(srctree)/tools/docs/sphinx-pre-install --version-check - +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ \ - --sphinxdirs=3D"$(SPHINXDIRS)" --conf=3D"$(SPHINX_CONF)" \ + +$(Q)$(PYTHON3) $(BUILD_WRAPPER) $@ $(RUSTDOC)\ + --sphinxdirs=3D"$(SPHINXDIRS)" --conf=3D"$(SPHINX_CONF)" $(RUSTDOC)\ --builddir=3D"$(BUILDDIR)" --deny-vf=3D$(FONTS_CONF_DENY_VF) \ --theme=3D$(DOCS_THEME) --css=3D$(DOCS_CSS) --paper=3D$(PAPER) =20 @@ -67,24 +72,6 @@ pdfdocs: @echo " SKIP Sphinx $@ target." endif =20 -# HTML main logic is identical to other targets. However, if rust is enabl= ed, -# 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=3D"$(SPHINXDIRS)" --conf=3D"$(SPHINX_CONF)" \ - --builddir=3D"$(BUILDDIR)" \ - --theme=3D$(DOCS_THEME) --css=3D$(DOCS_CSS) --paper=3D$(PAPER) -# If Rust support is available and .config exists, add rustdoc generated c= ontents. -# 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 =20 # The following targets are independent of HAVE_SPHINX, and the rules shou= ld diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per 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. """ =20 - def is_rust_enabled(self): - """Check if rust is enabled at .config""" - config_path =3D os.path.join(self.srctree, ".config") - if os.path.isfile(config_path): - with open(config_path, "r", encoding=3D"utf-8") as f: - return "CONFIG_RUST=3Dy" in f.read() - return False - def get_path(self, path, use_cwd=3DFalse, abs_path=3DFalse): """ Ancillary routine to handle patches the right way, as shell does. @@ -218,8 +210,6 @@ class SphinxBuilder: "scripts/kernel-doc.= py")) self.builddir =3D self.get_path(builddir, use_cwd=3DTrue, abs_path= =3DTrue) =20 - self.config_rust =3D self.is_rust_enabled() - # # Get directory locations for LaTeX build toolchain # @@ -274,7 +264,7 @@ class SphinxBuilder: =20 return subprocess.call(cmd, *args, **pwargs) =20 - def handle_html(self, css, output_dir): + def handle_html(self, css, output_dir, rustdoc): """ Extra steps for HTML and epub output. =20 @@ -282,20 +272,34 @@ class SphinxBuilder: copied to the output _static directory """ =20 - if not css: - return + if css: + css =3D os.path.expanduser(css) + if not css.startswith("/"): + css =3D os.path.join(self.srctree, css) =20 - css =3D os.path.expanduser(css) - if not css.startswith("/"): - css =3D os.path.join(self.srctree, css) + static_dir =3D os.path.join(output_dir, "_static") + os.makedirs(static_dir, exist_ok=3DTrue) =20 - static_dir =3D os.path.join(output_dir, "_static") - os.makedirs(static_dir, exist_ok=3DTrue) + try: + shutil.copy2(css, static_dir) + except (OSError, IOError) as e: + print(f"Warning: Failed to copy CSS: {e}", file=3Dsys.stde= rr) =20 - try: - shutil.copy2(css, static_dir) - except (OSError, IOError) as e: - print(f"Warning: Failed to copy CSS: {e}", file=3Dsys.stderr) + if rustdoc: + if "MAKE" in self.env: + cmd =3D [self.env["MAKE"]] + else: + cmd =3D ["make", "LLVM=3D1"] + + cmd +=3D [ "rustdoc"] + if self.verbose: + print(" ".join(cmd)) + + try: + subprocess.run(cmd, check=3DTrue) + except subprocess.CalledProcessError as e: + print(f"Ignored errors when building rustdoc: {e}. Is RUST= enabled?", + file=3Dsys.stderr) =20 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=3DTrue) =20 def build(self, target, sphinxdirs=3DNone, conf=3D"conf.py", - theme=3DNone, css=3DNone, paper=3DNone, deny_vf=3DNone): + theme=3DNone, css=3DNone, paper=3DNone, deny_vf=3DNone, rust= doc=3DFalse): """ 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: =20 args.extend(["-D", f"latex_elements.papersize=3D{paper}paper"]) =20 - if self.config_rust: + if rustdoc: args.extend(["-t", "rustdoc"]) =20 if conf: @@ -699,7 +703,7 @@ class SphinxBuilder: # Ensure that each html/epub output will have needed static fi= les # if target in ["htmldocs", "epubdocs"]: - self.handle_html(css, output_dir) + self.handle_html(css, output_dir, rustdoc) =20 # # Step 2: Some targets (PDF and info) require an extra step once @@ -756,6 +760,9 @@ def main(): parser.add_argument('--deny-vf', help=3D"Configuration to deny variable fonts on pd= f builds") =20 + parser.add_argument('--rustdoc', action=3D"store_true", + help=3D"Enable rustdoc build. Requires CONFIG_RUST= ") + parser.add_argument("-v", "--verbose", action=3D'store_true', help=3D"place build in verbose mode") =20 @@ -775,7 +782,7 @@ def main(): =20 builder.build(args.target, sphinxdirs=3Dargs.sphinxdirs, conf=3Dargs.c= onf, theme=3Dargs.theme, css=3Dargs.css, paper=3Dargs.paper, - deny_vf=3Dargs.deny_vf) + rustdoc=3Dargs.rustdoc, deny_vf=3Dargs.deny_vf) =20 if __name__ =3D=3D "__main__": main() --=20 2.51.0