[PATCH 0/1] fix rustdoc build detection

[PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Hi Jon,

For whatever weird reason, at least here sometimes rust config
detection is failing, causing the logic to try building the Kernel
as well, after building the docs.

After some tests, I'm opting to move the rust detection to be inside
the wrapper, at it sounds to me that the building system is not
evaluating well CONFIG_RUST here:

	ifeq ($(CONFIG_RUST),y)
	       RUSTDOC=--rustdoc
	endif

Another alternative would be to modify the rustdoc target inside
rust Makefile to make it dependent on htmldocs, but that would require
more work.

Mauro Carvalho Chehab (1):
  docs: makefile: move rustdoc check to the build wrapper

 Documentation/Makefile          |  6 -----
 tools/docs/sphinx-build-wrapper | 41 +++++++++++++++++++++++++--------
 2 files changed, 32 insertions(+), 15 deletions(-)

-- 
2.51.1

[PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Mauro Carvalho Chehab]

The makefile logic to detect if rust is enabled is not working
the way it was expected. Move it to be inside the wrapper
script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile          |  6 -----
 tools/docs/sphinx-build-wrapper | 41 +++++++++++++++++++++++++--------
 2 files changed, 32 insertions(+), 15 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d514ab6761dc..d4c42aa89439 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -42,12 +42,6 @@ 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)
 
-ifneq ($(wildcard $(srctree)/.config),)
-ifeq ($(CONFIG_RUST),y)
-	RUSTDOC=--rustdoc
-endif
-endif
-
 ifeq ($(HAVE_SPHINX),0)
 
 .DEFAULT:
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 1efaca3d16aa..a554176b5a06 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -119,6 +119,29 @@ class SphinxBuilder:
 
         return path
 
+    def check_rust(self):
+        """
+        Checks if Rust is enabled
+        """
+        self.rustdoc = False
+
+        config = os.path.join(self.srctree, ".config")
+
+        if not os.path.isfile(config):
+            return
+
+        re_rust = re.compile(r"CONFIG_RUST=(m|y)")
+
+        try:
+            with open(config, "r", encoding="utf-8") as fp:
+                for line in fp:
+                    if re_rust.match(line):
+                        self.rustdoc = True
+                        return
+
+        except OSError as e:
+            print(f"Failed to open {config}", file=sys.stderr)
+
     def get_sphinx_extra_opts(self, n_jobs):
         """
         Get the number of jobs to be used for docs build passed via command
@@ -236,6 +259,8 @@ class SphinxBuilder:
 
         self.get_sphinx_extra_opts(n_jobs)
 
+        self.check_rust()
+
         #
         # If venv command line argument is specified, run Sphinx from venv
         #
@@ -306,7 +331,7 @@ class SphinxBuilder:
 
             return subprocess.call(cmd, *args, **pwargs)
 
-    def handle_html(self, css, output_dir, rustdoc):
+    def handle_html(self, css, output_dir):
         """
         Extra steps for HTML and epub output.
 
@@ -327,7 +352,8 @@ class SphinxBuilder:
             except (OSError, IOError) as e:
                 print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr)
 
-        if rustdoc:
+        if self.rustdoc:
+            print("Building rust docs")
             if "MAKE" in self.env:
                 cmd = [self.env["MAKE"]]
             else:
@@ -622,7 +648,7 @@ class SphinxBuilder:
         shutil.rmtree(self.builddir, ignore_errors=True)
 
     def build(self, target, sphinxdirs=None,
-              theme=None, css=None, paper=None, deny_vf=None, rustdoc=False,
+              theme=None, css=None, paper=None, deny_vf=None,
               skip_sphinx=False):
         """
         Build documentation using Sphinx. This is the core function of this
@@ -671,7 +697,7 @@ class SphinxBuilder:
 
             args.extend(["-D", f"latex_elements.papersize={paper}paper"])
 
-        if rustdoc:
+        if self.rustdoc:
             args.extend(["-t", "rustdoc"])
 
         if not sphinxdirs:
@@ -749,7 +775,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, rustdoc)
+                self.handle_html(css, output_dir)
 
         #
         # Step 2: Some targets (PDF and info) require an extra step once
@@ -804,9 +830,6 @@ 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")
 
@@ -834,7 +857,7 @@ def main():
 
     builder.build(args.target, sphinxdirs=args.sphinxdirs,
                   theme=args.theme, css=args.css, paper=args.paper,
-                  rustdoc=args.rustdoc, deny_vf=args.deny_vf,
+                  deny_vf=args.deny_vf,
                   skip_sphinx=args.skip_sphinx_build)
 
 if __name__ == "__main__":
-- 
2.51.1

Re: [PATCH 0/1] fix rustdoc build detection

[Miguel Ojeda]

On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Another alternative would be to modify the rustdoc target inside
> rust Makefile to make it dependent on htmldocs, but that would require
> more work.

Why? No, there is no need to build any htmldocs to build the Rust
documentation, so that would be wrong.

Cheers,
Miguel

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Miguel Ojeda]

On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> The makefile logic to detect if rust is enabled is not working
> the way it was expected. Move it to be inside the wrapper
> script.

Hmm... Could the commit explain a bit why this didn't work and why now it does?

Thanks!

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

On Mon, Nov 17, 2025 at 10:19:18AM +0100, Miguel Ojeda wrote:
> On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Another alternative would be to modify the rustdoc target inside
> > rust Makefile to make it dependent on htmldocs, but that would require
> > more work.
> 
> Why? No, there is no need to build any htmldocs to build the Rust
> documentation, so that would be wrong.

Sure, Sphinx (including kernel-doc) build and rust doca build are
independent. Yet, Makefile "htmldocs" target currently does both. 

It could make sense to have a separate target if one want to build
them both, e.g. something like:

    make rustdoc - builds just rust docs
    make htmldocs - builds all non-rust docs
    make allhtmldocs - makes both

On other words, we could add a rule like:

    rusthtmldocs: rustdoc htmldocs

and simplify the makefile and the wrapper.

PS.: I'm using "allhtmldocs" just to make clear about what
     I meant. Not sure if this would be the best name for the
     joint html output target.

-- 
Thanks,
Mauro

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Mauro Carvalho Chehab]

On Mon, Nov 17, 2025 at 10:20:46AM +0100, Miguel Ojeda wrote:
> On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > The makefile logic to detect if rust is enabled is not working
> > the way it was expected. Move it to be inside the wrapper
> > script.
> 
> Hmm... Could the commit explain a bit why this didn't work and why now it does?

I don't know exactly why this was not working.

I guess one of the issues is that the "rustdoc" target becomes
undefined if RUST is not enabled, e.g. rust/Makefile is lacking something
like:

    ifdef CONFIG_RUST
    ...
    else
    rustdoc rustdoc-core rustdoc-macros rustdoc-compiler_builtins:
            $(warning Rust is not enabled. Can't build $<)    
    endif

But this is not enough to explain the issues I'm getting.

Maybe the other issues are cache related.

In any case, here, with Fedora 43, on some cases, when I run:

    make htmldocs  # or make SPHINXDIRS=xxx htmldocs

it sometimes, after building the docs, it tries to run:

    make LLVM=1 rustdoc

as this is not a defined target when CONFIG_RUST is not
present, this causes it to build the entire code.

-- 
Thanks,
Mauro

Re: [PATCH 0/1] fix rustdoc build detection

[Miguel Ojeda]

On Mon, Nov 17, 2025 at 11:48 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Sure, Sphinx (including kernel-doc) build and rust doca build are
> independent. Yet, Makefile "htmldocs" target currently does both.
>
> It could make sense to have a separate target if one want to build
> them both, e.g. something like:

My understanding (Cc'ing Carlos) is that the idea was that `htmldocs`
built the Rust docs if possible.

I don't mind if that is changed etc., but I think it is important to
keep the `rustdoc` target simple and focused: it is a "basic"
operation (which is also used to lint docs too), and way faster than
building the HTML docs, and it doesn't depend on them.

Apologies if I put it perhaps a bit too tersely in my previous message
-- everyone contributing to Rust code is supposed to rely on that
target to test their commits, and needing the whole Sphinx setup would
make the target way worse in practice.

Now, in the future, if we start relying on generating references for
the Rust docs from the C side and things like that (which is my plan,
but it is long term: first item in
https://github.com/Rust-for-Linux/linux/issues/350), we may need to
rethink things a bit (i.e. we may need to run a subset of the kernel
normal docs to build the Rust docs), but even then ideally we should
only introduce the minimal dependency needed.

I hope that clarifies -- thanks!

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Miguel Ojeda]

On Mon, Nov 17, 2025 at 12:22 PM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> I don't mind if that is changed etc., but I think it is important to
> keep the `rustdoc` target simple and focused: it is a "basic"
> operation (which is also used to lint docs too), and way faster than
> building the HTML docs, and it doesn't depend on them.

It is also the target I use to build rust.docs.kernel.org, for instance.

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Mon, 17 Nov 2025 12:22:48 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Mon, Nov 17, 2025 at 11:48 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Sure, Sphinx (including kernel-doc) build and rust doca build are
> > independent. Yet, Makefile "htmldocs" target currently does both.
> >
> > It could make sense to have a separate target if one want to build
> > them both, e.g. something like:  
> 
> My understanding (Cc'ing Carlos) is that the idea was that `htmldocs`
> built the Rust docs if possible.
> 
> I don't mind if that is changed etc., but I think it is important to
> keep the `rustdoc` target simple and focused: it is a "basic"
> operation (which is also used to lint docs too), and way faster than
> building the HTML docs, and it doesn't depend on them.

Heh, the same applies to the current usage of htmldocs - specially
when SPHINXDIRS is used, e.g. one doing, for instance:

	make SPHINXDOCS=driver-api/<subsystem>

may not be interested on building rust docs, which, on such case,
may be a lot slower than a partial build. Also, I don't think that
rustdoc currently does something similar to SPHINXDOCS.

So, at least for me, it does make sense to have separate targets
for Sphinx, Rust and both (*).

(*) now, how such targets would be named is a completely different
    question.

> Apologies if I put it perhaps a bit too tersely in my previous message
> -- everyone contributing to Rust code is supposed to rely on that
> target to test their commits, and needing the whole Sphinx setup would
> make the target way worse in practice.

Agreed.

> 
> Now, in the future, if we start relying on generating references for
> the Rust docs from the C side and things like that (which is my plan,
> but it is long term: first item in
> https://github.com/Rust-for-Linux/linux/issues/350), we may need to
> rethink things a bit (i.e. we may need to run a subset of the kernel
> normal docs to build the Rust docs), but even then ideally we should
> only introduce the minimal dependency needed.

IMO, this is a separate discussion, as you may need a different
toolset.

The way I see, for issue #350 IMO the best would be to create a 
Sphinx extension similar to:

	Documentation/sphinx/parser_yaml.py

E.g. you would create a parser_rust.py module there, which would
generate ReST output from the rust code(*). Besides allowing cross
references between Sphinx, C and Rust, this would also allow
generating epub and pdf output.

(*) In practice, teaching rustdoc how to produce ReST output.
    Alternatively, rustdoc could generate a markdown output and use
    a sphinx markdown extension at parser_rust.py, to convert from
    MD to ReST like this extension:

	https://www.sphinx-doc.org/en/master/usage/markdown.html

Besides allowing cross references between Sphinx, C and Rust, a Sphinx
extension would also allow generating epub and pdf output, removing
all extra Makefile (or wrapper) code related to rustdoc.

-

Another alternative would be to use intersphinx, but I guess
making it working would be a lot more complex - as we don't even
support it yet on our current Sphinx output.
	

Thanks,
Mauro

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> On Mon, Nov 17, 2025 at 10:20:46AM +0100, Miguel Ojeda wrote:
>> On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
>> <mchehab+huawei@kernel.org> wrote:
>> >
>> > The makefile logic to detect if rust is enabled is not working
>> > the way it was expected. Move it to be inside the wrapper
>> > script.
>> 
>> Hmm... Could the commit explain a bit why this didn't work and why now it does?
>
> I don't know exactly why this was not working.

I would feel a lot better if we knew what the real problem is before
applying fixes for it.  Otherwise something seems certain to come and
bite us at some point.

Thanks,

jon

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 09:38:15 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > On Mon, Nov 17, 2025 at 10:20:46AM +0100, Miguel Ojeda wrote:  
> >> On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
> >> <mchehab+huawei@kernel.org> wrote:  
> >> >
> >> > The makefile logic to detect if rust is enabled is not working
> >> > the way it was expected. Move it to be inside the wrapper
> >> > script.  
> >> 
> >> Hmm... Could the commit explain a bit why this didn't work and why now it does?  
> >
> > I don't know exactly why this was not working.  
> 
> I would feel a lot better if we knew what the real problem is before
> applying fixes for it.  Otherwise something seems certain to come and
> bite us at some point.

Me too, but the bug is very annoying ;-)

I'll try to seek for some time to better understand it, maybe
next week.

Thanks,
Mauro

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 20:11:52 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Tue, 18 Nov 2025 09:38:15 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >   
> > > On Mon, Nov 17, 2025 at 10:20:46AM +0100, Miguel Ojeda wrote:    
> > >> On Mon, Nov 17, 2025 at 10:13 AM Mauro Carvalho Chehab
> > >> <mchehab+huawei@kernel.org> wrote:    
> > >> >
> > >> > The makefile logic to detect if rust is enabled is not working
> > >> > the way it was expected. Move it to be inside the wrapper
> > >> > script.    
> > >> 
> > >> Hmm... Could the commit explain a bit why this didn't work and why now it does?    
> > >
> > > I don't know exactly why this was not working.    
> > 
> > I would feel a lot better if we knew what the real problem is before
> > applying fixes for it.  Otherwise something seems certain to come and
> > bite us at some point.  
> 
> Me too, but the bug is very annoying ;-)
> 
> I'll try to seek for some time to better understand it, maybe
> next week.

Btw, at least here (Fedora 43, upgraded from 42), rustdoc doesn't build
for docs-next.

Perhaps the issue could be due to some weird things with Fedora 43.

That's what happens after sphinx-build-wrapper finishes handling
htmldocs (after this patch), when it runs "make LLVM=1 rustdoc":

Building rust docs
  DESCEND objtool
  INSTALL libsubcmd_headers
  CALL    scripts/checksyscalls.sh
  RUSTC L rust/bindings.o
  RUSTC L rust/build_error.o
  RUSTC L rust/uapi.o
error: mixing `-Zsanitizer` will cause an ABI mismatch in crate `build_error`
 --> rust/build_error.rs:3:1
  |
3 | //! Build-time error.
  | ^
  |
  = help: the `-Zsanitizer` flag modifies the ABI so Rust crates compiled with different values of this flag cannot be used together safely
  = note: unset `-Zsanitizer` in this crate is incompatible with `-Zsanitizer=kernel-address` in dependency `core`
  = help: set `-Zsanitizer=kernel-address` in this crate or unset `-Zsanitizer` in `core`
  = help: if you are sure this will not cause problems, you may use `-Cunsafe-allow-abi-mismatch=sanitizer` to silence this error

error: mixing `-Zsanitizer` will cause an ABI mismatch in crate `build_error`
 --> rust/build_error.rs:3:1
  |
3 | //! Build-time error.
  | ^
  |
  = help: the `-Zsanitizer` flag modifies the ABI so Rust crates compiled with different values of this flag cannot be used together safely
  = note: unset `-Zsanitizer` in this crate is incompatible with `-Zsanitizer=kernel-address` in dependency `compiler_builtins`
  = help: set `-Zsanitizer=kernel-address` in this crate or unset `-Zsanitizer` in `compiler_builtins`
  = help: if you are sure this will not cause problems, you may use `-Cunsafe-allow-abi-mismatch=sanitizer` to silence this error

error: aborting due to 2 previous errors

make[4]: *** [rust/Makefile:527: rust/build_error.o] Error 1
make[4]: ** Esperando que outros processos terminem.
make[3]: *** [Makefile:1286: prepare] Error 2
Ignored errors when building rustdoc: Command '['make', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?

Relevant Rust configs:

$ grep RUST .config
CONFIG_RUSTC_VERSION=109100
CONFIG_RUST_IS_AVAILABLE=y
CONFIG_RUSTC_LLVM_VERSION=210103
CONFIG_RUSTC_HAS_COERCE_POINTEE=y
CONFIG_RUSTC_HAS_SPAN_FILE=y
CONFIG_RUSTC_HAS_UNNECESSARY_TRANSMUTES=y
CONFIG_RUSTC_HAS_FILE_WITH_NUL=y
CONFIG_RUSTC_HAS_FILE_AS_C_STR=y
CONFIG_RUST=y
CONFIG_RUSTC_VERSION_TEXT="rustc 1.91.0 (f8297e351 2025-10-28) (Fedora 1.91.0-1.fc43)"
# CONFIG_CPUFREQ_DT_RUST is not set
CONFIG_HAVE_RUST=y
# CONFIG_RUST_FW_LOADER_ABSTRACTIONS is not set
# CONFIG_BLK_DEV_RUST_NULL is not set
# CONFIG_RUST_PHYLIB_ABSTRACTIONS is not set
CONFIG_RADIO_TRUST=y
CONFIG_RADIO_TRUST_PORT=350
CONFIG_HID_THRUSTMASTER=y
CONFIG_THRUSTMASTER_FF=y
CONFIG_TRUSTED_KEYS=y
CONFIG_HAVE_TRUSTED_KEYS=y
CONFIG_TRUSTED_KEYS_TPM=y
CONFIG_TRUSTED_KEYS_TEE=y
CONFIG_TRUSTED_KEYS_CAAM=y
CONFIG_INTEGRITY_TRUSTED_KEYRING=y
CONFIG_IMA_SECURE_AND_OR_TRUSTED_BOOT=y
# CONFIG_RUST_BITMAP_HARDENED is not set
CONFIG_SYSTEM_TRUSTED_KEYRING=y
CONFIG_SYSTEM_TRUSTED_KEYS=""
CONFIG_SECONDARY_TRUSTED_KEYRING=y
CONFIG_SECONDARY_TRUSTED_KEYRING_SIGNED_BY_BUILTIN=y
# CONFIG_SAMPLES_RUST is not set
# CONFIG_FIND_BIT_BENCHMARK_RUST is not set
# CONFIG_RUST_DEBUG_ASSERTIONS is not set
CONFIG_RUST_OVERFLOW_CHECKS=y
# CONFIG_RUST_BUILD_ASSERT_ALLOW is not set
CONFIG_RUST_KERNEL_DOCTESTS=y



Thanks,
Mauro

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Miguel Ojeda]

On Tue, Nov 18, 2025 at 9:32 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Btw, at least here (Fedora 43, upgraded from 42), rustdoc doesn't build
> for docs-next.
>
> Perhaps the issue could be due to some weird things with Fedora 43.
>
> That's what happens after sphinx-build-wrapper finishes handling
> htmldocs (after this patch), when it runs "make LLVM=1 rustdoc":

That one is fixed with commit 16c43a56b79e ("rust: kbuild: treat
`build_error` and `rustdoc` as kernel objects") which is in -rc5.

Cheers,
Miguel

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Miguel Ojeda]

On Tue, Nov 18, 2025 at 8:12 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Me too, but the bug is very annoying ;-)
>
> I'll try to seek for some time to better understand it, maybe
> next week.

I will try to find a moment to take a look too... This happens with
only the new wrapper, right? Or is it something that happened even
before? If the latter, I remember testing the logic that Carlos added
a long time ago, but maybe something changed in the meantime.

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Miguel Ojeda]

On Mon, Nov 17, 2025 at 1:32 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Heh, the same applies to the current usage of htmldocs - specially
> when SPHINXDIRS is used, e.g. one doing, for instance:
>
>         make SPHINXDOCS=driver-api/<subsystem>
>
> may not be interested on building rust docs, which, on such case,
> may be a lot slower than a partial build. Also, I don't think that
> rustdoc currently does something similar to SPHINXDOCS.

If you mean building the Rust docs introduces extra work for people
building the HTML docs when that happens automatically, then yeah,
definitely.

Perhaps it could be skipped depending on what folders are requested.

> E.g. you would create a parser_rust.py module there, which would
> generate ReST output from the rust code(*).

To clarify, the idea of the "external references map file" in that
issue isn't to stop using `rustdoc`, but rather to allow `rustdoc` to
have (at least) the references to C items (e.g. a link to the rendered
`printk` docs at least to the source code where it is defined). In
other words, it is about allowing developrers to just write something
like [`printk()`] and the system would figure out how to link to the
right docs automatically.

We don't plan to stop using `rustdoc` -- its output is specialized for
Rust which makes it quite nice.

`rustdoc` can export JSON and that should be possible to use easily
from a Sphinx plugin without having to parse Rust from scratch, to at
least get some degree of Sphinx support. That would be nice for the
other outputs support like PDF as you mention, yeah, as well as having
independent-to-the-config docs. We discussed it a few times, but it
has never been a high priority, especially since `rustdoc` does its
job quite well.

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Carlos Bilbao]

Hey there,

On 11/17/25 05:22, Miguel Ojeda wrote:
> On Mon, Nov 17, 2025 at 11:48 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
>> Sure, Sphinx (including kernel-doc) build and rust doca build are
>> independent. Yet, Makefile "htmldocs" target currently does both.
>>
>> It could make sense to have a separate target if one want to build
>> them both, e.g. something like:
> My understanding (Cc'ing Carlos) is that the idea was that `htmldocs`
> built the Rust docs if possible.


Thanks! I'll also take a look at this, although I fear it'll be complicated
without a way to reproduce what Mauro experienced.


>
> I don't mind if that is changed etc., but I think it is important to
> keep the `rustdoc` target simple and focused: it is a "basic"
> operation (which is also used to lint docs too), and way faster than
> building the HTML docs, and it doesn't depend on them.
>
> Apologies if I put it perhaps a bit too tersely in my previous message
> -- everyone contributing to Rust code is supposed to rely on that
> target to test their commits, and needing the whole Sphinx setup would
> make the target way worse in practice.
>
> Now, in the future, if we start relying on generating references for
> the Rust docs from the C side and things like that (which is my plan,
> but it is long term: first item in
> https://github.com/Rust-for-Linux/linux/issues/350), we may need to
> rethink things a bit (i.e. we may need to run a subset of the kernel
> normal docs to build the Rust docs), but even then ideally we should
> only introduce the minimal dependency needed.
>
> I hope that clarifies -- thanks!
>
> Cheers,
> Miguel

Thanks,

Carlos

Re: [PATCH 1/1] docs: makefile: move rustdoc check to the build wrapper

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 22:40:09 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Tue, Nov 18, 2025 at 8:12 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Me too, but the bug is very annoying ;-)
> >
> > I'll try to seek for some time to better understand it, maybe
> > next week.  
> 
> I will try to find a moment to take a look too... This happens with
> only the new wrapper, right? Or is it something that happened even
> before? If the latter, I remember testing the logic that Carlos added
> a long time ago, but maybe something changed in the meantime.

I'm testing here against docs/docs-next, so it is based on -rc1,
so, yeah this is after the cleanups. The problem could be introduced
by the Makefile cleanup, but I didn't find anything obvious
but I haven't time to revisit after sending the patch, as I got
sidetracked with unrelated issues (*).

I'll try testing it tomorrow against linux-next.

Thanks,
Mauro

---

(*) I was preparing a new rasdaemon release, which was launched
    today.

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 17:23:48 -0600
Carlos Bilbao <carlos.bilbao.osdev@gmail.com> escreveu:

> Hey there,
> 
> On 11/17/25 05:22, Miguel Ojeda wrote:
> > On Mon, Nov 17, 2025 at 11:48 AM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:  
> >> Sure, Sphinx (including kernel-doc) build and rust doca build are
> >> independent. Yet, Makefile "htmldocs" target currently does both.
> >>
> >> It could make sense to have a separate target if one want to build
> >> them both, e.g. something like:  
> > My understanding (Cc'ing Carlos) is that the idea was that `htmldocs`
> > built the Rust docs if possible.  
> 
> 
> Thanks! I'll also take a look at this, although I fear it'll be complicated
> without a way to reproduce what Mauro experienced.

I was able to get the scenario on linux-next. It is a little bit
tricky to reproduce.

1) I did a build with:

	$ make distclean
	$ make SPHINXDIRS=peci htmldocs

   rustdoc was not called.

2) copied a .config that has CONFIG_RUST there:

	$ cp config-rust .config
	$ make SPHINXDIRS=peci htmldocs

   rustdoc was not called.

3) manually called rustdoc:

	$ make rustdoc

   rustdoc was built.

4) now, I re-ran htmldocs:

	$ make SPHINXDIRS=peci htmldocs

   rustdoc was built.

5) I replaced .config with a config without rust:

	$ make allyesconfig
	$ make SPHINXDIRS=peci htmldocs
	...
	Using alabaster theme
	Using Python kernel-doc
	  SYNC    include/config/auto.conf
	  HOSTCC  scripts/basic/fixdep
	  DESCEND objtool
	  INSTALL libsubcmd_headers
	  CC      scripts/mod/empty.o
	  CC      scripts/mod/devicetable-offsets.s
	  MKELF   scripts/mod/elfconfig.h
	  HOSTCC  scripts/mod/modpost.o
	  HOSTCC  scripts/mod/sumversion.o
	  HOSTCC  scripts/mod/symsearch.o
	  HOSTCC  scripts/mod/file2alias.o
	  HOSTLD  scripts/mod/modpost
	  CC      kernel/bounds.s
	  CC      arch/x86/kernel/asm-offsets.s
	  UPD     include/generated/asm-offsets.h
	  CC      kernel/sched/rq-offsets.s
	  CALL    scripts/checksyscalls.sh
	make[4]: *** No rule to make target 'rustdoc'.  Stop.
	make[3]: *** [Makefile:1855: rustdoc] Error 2
	Ignored errors when building rustdoc: Command '['make', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?

There are other combinations that produce weird things.

If, instead of step (5), we do:

	$ echo >.config
	$ LANG=C make SPHINXDIRS=peci htmldocs

it will produce, after building htmldocs from Sphinx:

	Using alabaster theme
	Using Python kernel-doc
	  SYNC    include/config/auto.conf
	  HOSTCC  scripts/basic/fixdep
	*
	* Restart config...
	*
	*
	* General setup
	*
	Compile also drivers which will not load (COMPILE_TEST) [N/y/?] (NEW) 

---

My understanding is that the issue is caused because (by purpose)
make htmldocs doesn't sync configuration. It doesn't need, as
building docs doesn't really depend on any .config flag.

However, this check at the Makefile:

	ifneq ($(wildcard $(srctree)/.config),)
	ifeq ($(CONFIG_RUST),y)
        	RUSTDOC=--rustdoc
	endif
	endif

Uses a cached value of "CONFIG_RUST" from the last build, with may
or may not be present anymore.

My patch solves this by not using the cached result, but, instead
checking if CONFIG_RUST is enabled directly at the .config file.

Thanks,
Mauro

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Tue, 18 Nov 2025 23:02:35 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Mon, Nov 17, 2025 at 1:32 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Heh, the same applies to the current usage of htmldocs - specially
> > when SPHINXDIRS is used, e.g. one doing, for instance:
> >
> >         make SPHINXDOCS=driver-api/<subsystem>
> >
> > may not be interested on building rust docs, which, on such case,
> > may be a lot slower than a partial build. Also, I don't think that
> > rustdoc currently does something similar to SPHINXDOCS.  
> 
> If you mean building the Rust docs introduces extra work for people
> building the HTML docs when that happens automatically, then yeah,
> definitely.
> 
> Perhaps it could be skipped depending on what folders are requested.

Yeah, that sounds a good approach: teach rustdoc target to handle
SPHINXDOCS. If it is empty (or just ".") handle the same way as
today. Otherwise, do a partial doc build or skip when it doesn't
make sense.

> 
> > E.g. you would create a parser_rust.py module there, which would
> > generate ReST output from the rust code(*).  
> 
> To clarify, the idea of the "external references map file" in that
> issue isn't to stop using `rustdoc`, 

I'm not talking about stop using rustdoc. I'm talking about using
it to output on a format that Sphinx can understand, and let Sphinx
do the final output, solving cross-references.

> but rather to allow `rustdoc` to
> have (at least) the references to C items (e.g. a link to the rendered
> `printk` docs at least to the source code where it is defined). In
> other words, it is about allowing developrers to just write something
> like [`printk()`] and the system would figure out how to link to the
> right docs automatically.
> 
> We don't plan to stop using `rustdoc` -- its output is specialized for
> Rust which makes it quite nice.
> 
> `rustdoc` can export JSON and that should be possible to use easily
> from a Sphinx plugin without having to parse Rust from scratch, to at
> least get some degree of Sphinx support. 

There is a JSON Sphinx plugin (although I never used - no idea if
it would do what it is needed):
	https://sphinx-jsonschema.readthedocs.io/en/latest/

If this won't work, I guess it wouldn't be hard to use parser_yaml.py as
an example to write a new plugin to handle rustdoc JSON output.

> That would be nice for the
> other outputs support like PDF as you mention, yeah, as well as having
> independent-to-the-config docs. We discussed it a few times, but it
> has never been a high priority, especially since `rustdoc` does its
> job quite well.

Thanks,
Mauro

Re: [PATCH 0/1] fix rustdoc build detection

[Miguel Ojeda]

On Fri, Nov 21, 2025 at 10:41 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> I'm not talking about stop using rustdoc. I'm talking about using
> it to output on a format that Sphinx can understand, and let Sphinx
> do the final output, solving cross-references.

By stop using `rustdoc` I meant its "normal" (HTML) output, i.e. the
webpage with all its features and so on.

The JSON support is unstable so far:

    https://github.com/rust-lang/rust/issues/76578

And even then, I imagine it will always still require a kernel config,
so that isn't an advantage either.

Thus trying to mimic what `rustdoc` does is probably going to be a lot
of work to maintain, to likely get a worse result than what `rustdoc`
already does.

Something that would work without a config could be way more
interesting for us to integrate into Sphinx.

Thanks!

Cheers,
Miguel

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Mon, 24 Nov 2025 02:51:40 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Fri, Nov 21, 2025 at 10:41 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > I'm not talking about stop using rustdoc. I'm talking about using
> > it to output on a format that Sphinx can understand, and let Sphinx
> > do the final output, solving cross-references.  
> 
> By stop using `rustdoc` I meant its "normal" (HTML) output, i.e. the
> webpage with all its features and so on.

I see.

> The JSON support is unstable so far:
> 
>     https://github.com/rust-lang/rust/issues/76578

From the issue timestamps, it seems that it doesn't have a high
priority.

> And even then, I imagine it will always still require a kernel config,
> so that isn't an advantage either.

This doesn't seem to be an issue itself, as a new kernel config is easy 
to add.

> Thus trying to mimic what `rustdoc` does is probably going to be a lot
> of work to maintain, to likely get a worse result than what `rustdoc`
> already does.

Perhaps one solution would be to write a new output plugin to make
rustdoc produce a better output format that could be easily mapped
by a Sphinx plugin (like producing an output on an enriched text
format like Markdown or ReST).

I can't evaluate how easy/hard would be to do that, as I'm not
familiar with Rust toolset.

> Something that would work without a config could be way more
> interesting for us to integrate into Sphinx.

At Sphinx side, it won't be hard to pick references from rustdoc.

At kernel_include extension:

	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/sphinx/kernel_include.py

I added a logic there to detect unsolved cross-references.

Currently, it just warns about unsolved references, but it won't 
be hard to modify a similar logic to solve it, pointing to a
rustdoc reference (if those are stable enough).

Doing the reverse can be trickier, though: internally, Sphinx
maps them via a C domain. The output plugin (html, pdf, ...)
is what converts such reference into an html (or pdf) tag.
Such mapping is version dependent.

There was a major rewrite at eh C domain on Sphinx 3.0 which
changed such mapping, but other versions may have changed it as well.

Also, there is an open issue that will likely change it once
fixed:

	https://github.com/sphinx-doc/sphinx/issues/7819
	https://github.com/sphinx-doc/sphinx/issues/8241

(last one closed as duplicate of #7819)

So, creating cross-references from rustdoc to Sphinx could
be tricky and hard to maintain, as it may require some checks
at rust/rustdoc side to verify Sphinx version.

Thanks,
Mauro

Re: [PATCH 0/1] fix rustdoc build detection

[Mauro Carvalho Chehab]

Em Mon, 24 Nov 2025 09:18:11 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Mon, 24 Nov 2025 02:51:40 +0100
> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:
> 
> > On Fri, Nov 21, 2025 at 10:41 AM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:
> > >
> > > I'm not talking about stop using rustdoc. I'm talking about using
> > > it to output on a format that Sphinx can understand, and let Sphinx
> > > do the final output, solving cross-references.  
> > 
> > By stop using `rustdoc` I meant its "normal" (HTML) output, i.e. the
> > webpage with all its features and so on.
> 
> I see.
> 
> > The JSON support is unstable so far:
> > 
> >     https://github.com/rust-lang/rust/issues/76578
> 
> From the issue timestamps, it seems that it doesn't have a high
> priority.
> 
> > And even then, I imagine it will always still require a kernel config,
> > so that isn't an advantage either.
> 
> This doesn't seem to be an issue itself, as a new kernel config is easy 
> to add.
> 
> > Thus trying to mimic what `rustdoc` does is probably going to be a lot
> > of work to maintain, to likely get a worse result than what `rustdoc`
> > already does.
> 
> Perhaps one solution would be to write a new output plugin to make
> rustdoc produce a better output format that could be easily mapped
> by a Sphinx plugin (like producing an output on an enriched text
> format like Markdown or ReST).
> 
> I can't evaluate how easy/hard would be to do that, as I'm not
> familiar with Rust toolset.
> 
> > Something that would work without a config could be way more
> > interesting for us to integrate into Sphinx.
> 
> At Sphinx side, it won't be hard to pick references from rustdoc.
> 
> At kernel_include extension:
> 
> 	https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/sphinx/kernel_include.py
> 
> I added a logic there to detect unsolved cross-references.
> 
> Currently, it just warns about unsolved references, but it won't 
> be hard to modify a similar logic to solve it, pointing to a
> rustdoc reference (if those are stable enough).
> 
> Doing the reverse can be trickier, though: internally, Sphinx
> maps them via a C domain. The output plugin (html, pdf, ...)
> is what converts such reference into an html (or pdf) tag.
> Such mapping is version dependent.
> 
> There was a major rewrite at eh C domain on Sphinx 3.0 which
> changed such mapping, but other versions may have changed it as well.
> 
> Also, there is an open issue that will likely change it once
> fixed:
> 
> 	https://github.com/sphinx-doc/sphinx/issues/7819
> 	https://github.com/sphinx-doc/sphinx/issues/8241
> 
> (last one closed as duplicate of #7819)
> 
> So, creating cross-references from rustdoc to Sphinx could
> be tricky and hard to maintain, as it may require some checks
> at rust/rustdoc side to verify Sphinx version.

In time:

by "rust/rustdoc side" I mean the cross-reference solver that
would run inside the Makefile target that will be called after
building Sphinx docs. 

It will likely be external tools inside the Kernel tree to identify
Sphinx and docutils versions, rust/rustodoc version, and do whatever
other check would be needed to detect the tags format and modify
the produced html output for the hyperlinks to work.


Thanks,
Mauro