[RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Miguel Ojeda]

In Rust 1.56.0 [1], rustdoc introduced the "jump to definition"
feature [2], i.e. the unstable flag `--generate-link-to-definition`.
It adds links to the source view of the documentation.

For instance, in the source view of `rust/kernel/sync.rs`, for this code:

    impl Default for LockClassKey {
        fn default() -> Self {
            Self::new()
        }
    }

It will add three hyperlinks:

  - `Default` points to the rendered "Trait `core::default::Default`"
    page (not the source view, since it goes to another crate, though
    this may change).

  - `LockClassKey` points to the `pub struct LockClassKey(...);` line
    in the same page, highlighting the line number.

  - `Self::new()` points to the `pub const fn new() -> Self { ... }`
    associated function, highlighting its line numbers (i.e. for the
    full function).

This makes the source view more useful and a bit closer to the experience
in e.g. the Elixir Cross Referencer [3].

I have provisionally enabled it for rust.docs.kernel.org [4] -- one can
take a look at the source view there for an example of how it looks like.

Thus enable it.

Cc: Guillaume Gomez <guillaume1.gomez@gmail.com>
Link: https://github.com/rust-lang/rust/pull/84176 [1]
Link: https://github.com/rust-lang/rust/issues/89095 [2]
Link: https://elixir.bootlin.com [3]
Link: https://rust.docs.kernel.org [4]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/Makefile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rust/Makefile b/rust/Makefile
index 1f10f92737f2..d311bcc30226 100644
--- a/rust/Makefile
+++ b/rust/Makefile
@@ -63,6 +63,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
 	OBJTREE=$(abspath $(objtree)) \
 	$(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
 		$(rustc_target_flags) -L$(objtree)/$(obj) \
+		-Zunstable-options --generate-link-to-definition \
 		--output $(rustdoc_output) \
 		--crate-name $(subst rustdoc-,,$@) \
 		$(if $(rustdoc_host),,--sysroot=/dev/null) \

base-commit: 7c626ce4bae1ac14f60076d00eafe71af30450ba
-- 
2.46.0

Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Gary Guo]

On Sun, 18 Aug 2024 16:12:49 +0200
Miguel Ojeda <ojeda@kernel.org> wrote:

> In Rust 1.56.0 [1], rustdoc introduced the "jump to definition"
> feature [2], i.e. the unstable flag `--generate-link-to-definition`.
> It adds links to the source view of the documentation.
> 
> For instance, in the source view of `rust/kernel/sync.rs`, for this code:
> 
>     impl Default for LockClassKey {
>         fn default() -> Self {
>             Self::new()
>         }
>     }
> 
> It will add three hyperlinks:
> 
>   - `Default` points to the rendered "Trait `core::default::Default`"
>     page (not the source view, since it goes to another crate, though
>     this may change).
> 
>   - `LockClassKey` points to the `pub struct LockClassKey(...);` line
>     in the same page, highlighting the line number.
> 
>   - `Self::new()` points to the `pub const fn new() -> Self { ... }`
>     associated function, highlighting its line numbers (i.e. for the
>     full function).
> 
> This makes the source view more useful and a bit closer to the experience
> in e.g. the Elixir Cross Referencer [3].
> 
> I have provisionally enabled it for rust.docs.kernel.org [4] -- one can
> take a look at the source view there for an example of how it looks like.
> 
> Thus enable it.
> 
> Cc: Guillaume Gomez <guillaume1.gomez@gmail.com>
> Link: https://github.com/rust-lang/rust/pull/84176 [1]
> Link: https://github.com/rust-lang/rust/issues/89095 [2]
> Link: https://elixir.bootlin.com [3]
> Link: https://rust.docs.kernel.org [4]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Hi Miguel,

Thanks for doing this! When I visited rust.docs.kernel.org yesterday I
noticed that the definition links already existed, and it was very
useful.

Reviewed-by: Gary Guo <gary@garyguo.net>

Best,
Gary


> ---
>  rust/Makefile | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/rust/Makefile b/rust/Makefile
> index 1f10f92737f2..d311bcc30226 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -63,6 +63,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>  	OBJTREE=$(abspath $(objtree)) \
>  	$(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
>  		$(rustc_target_flags) -L$(objtree)/$(obj) \
> +		-Zunstable-options --generate-link-to-definition \
>  		--output $(rustdoc_output) \
>  		--crate-name $(subst rustdoc-,,$@) \
>  		$(if $(rustdoc_host),,--sysroot=/dev/null) \
> 
> base-commit: 7c626ce4bae1ac14f60076d00eafe71af30450ba

Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Miguel Ojeda]

On Sun, Aug 18, 2024 at 8:19 PM Gary Guo <gary@garyguo.net> wrote:
>
> Thanks for doing this! When I visited rust.docs.kernel.org yesterday I
> noticed that the definition links already existed, and it was very
> useful.
>
> Reviewed-by: Gary Guo <gary@garyguo.net>

Thanks Gary, I appreciate that. Yeah, you caught me, I enabled it a
week or two ago. I am very glad you already found it useful :)

Cheers,
Miguel

Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Miguel Ojeda]

On Sun, Aug 18, 2024 at 4:13 PM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> In Rust 1.56.0 [1], rustdoc introduced the "jump to definition"
> feature [2], i.e. the unstable flag `--generate-link-to-definition`.
> It adds links to the source view of the documentation.
>
> For instance, in the source view of `rust/kernel/sync.rs`, for this code:
>
>     impl Default for LockClassKey {
>         fn default() -> Self {
>             Self::new()
>         }
>     }
>
> It will add three hyperlinks:
>
>   - `Default` points to the rendered "Trait `core::default::Default`"
>     page (not the source view, since it goes to another crate, though
>     this may change).
>
>   - `LockClassKey` points to the `pub struct LockClassKey(...);` line
>     in the same page, highlighting the line number.
>
>   - `Self::new()` points to the `pub const fn new() -> Self { ... }`
>     associated function, highlighting its line numbers (i.e. for the
>     full function).
>
> This makes the source view more useful and a bit closer to the experience
> in e.g. the Elixir Cross Referencer [3].
>
> I have provisionally enabled it for rust.docs.kernel.org [4] -- one can
> take a look at the source view there for an example of how it looks like.
>
> Thus enable it.
>
> Cc: Guillaume Gomez <guillaume1.gomez@gmail.com>
> Link: https://github.com/rust-lang/rust/pull/84176 [1]
> Link: https://github.com/rust-lang/rust/issues/89095 [2]
> Link: https://elixir.bootlin.com [3]
> Link: https://rust.docs.kernel.org [4]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Applied to `rust-next` -- thanks!

Let's enable this since it has already been useful for people. If it
happens to break, we can always disable it. And it may help getting it
stabilized.

Cheers,
Miguel

Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Guillaume Gomez]

Don't hesitate if you encounter any bug to tell me so I can fix them.

Any feedback is also very appreciated!


Le dim. 25 août 2024 à 22:22, Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> a écrit :
>
> On Sun, Aug 18, 2024 at 4:13 PM Miguel Ojeda <ojeda@kernel.org> wrote:
> >
> > In Rust 1.56.0 [1], rustdoc introduced the "jump to definition"
> > feature [2], i.e. the unstable flag `--generate-link-to-definition`.
> > It adds links to the source view of the documentation.
> >
> > For instance, in the source view of `rust/kernel/sync.rs`, for this code:
> >
> >     impl Default for LockClassKey {
> >         fn default() -> Self {
> >             Self::new()
> >         }
> >     }
> >
> > It will add three hyperlinks:
> >
> >   - `Default` points to the rendered "Trait `core::default::Default`"
> >     page (not the source view, since it goes to another crate, though
> >     this may change).
> >
> >   - `LockClassKey` points to the `pub struct LockClassKey(...);` line
> >     in the same page, highlighting the line number.
> >
> >   - `Self::new()` points to the `pub const fn new() -> Self { ... }`
> >     associated function, highlighting its line numbers (i.e. for the
> >     full function).
> >
> > This makes the source view more useful and a bit closer to the experience
> > in e.g. the Elixir Cross Referencer [3].
> >
> > I have provisionally enabled it for rust.docs.kernel.org [4] -- one can
> > take a look at the source view there for an example of how it looks like.
> >
> > Thus enable it.
> >
> > Cc: Guillaume Gomez <guillaume1.gomez@gmail.com>
> > Link: https://github.com/rust-lang/rust/pull/84176 [1]
> > Link: https://github.com/rust-lang/rust/issues/89095 [2]
> > Link: https://elixir.bootlin.com [3]
> > Link: https://rust.docs.kernel.org [4]
> > Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
>
> Applied to `rust-next` -- thanks!
>
> Let's enable this since it has already been useful for people. If it
> happens to break, we can always disable it. And it may help getting it
> stabilized.
>
> Cheers,
> Miguel

Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

[Miguel Ojeda]

On Sun, Aug 25, 2024 at 10:25 PM Guillaume Gomez
<guillaume1.gomez@gmail.com> wrote:
>
> Don't hesitate if you encounter any bug to tell me so I can fix them.
>
> Any feedback is also very appreciated!

Thanks Guillaume, that is very appreciated!

We will hopefully not have to tell you about any bugs :)

Cheers,
Miguel