[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local #139769

GuillaumeGomez · 2025-04-13T22:47:22Z

This option adds the possibility to provide a path or a URL to the associated guide of this crate in the crate-level doc page. If the provided argument is a path, then the guide is generated using the mdbook crate.

It looks like this:

You can give it a try here.

It'll need an FCP before getting merged.

Also I need to add tests when the argument is a path but I'll wait for the feature form to be final before doing it to prevent doing it more than once. 😄

cc @notriddle
r? @camelid

rustbot · 2025-04-13T22:47:29Z

These commits modify the Cargo.lock file. Unintentional changes to Cargo.lock can be introduced when switching branches and rebasing PRs.

If this was unintentional then you should revert the changes before this PR is merged.
Otherwise, you can ignore this comment.

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

rustbot · 2025-04-14T11:56:12Z

The list of allowed third-party dependencies may have been modified! You must ensure that any new dependencies have compatible licenses before merging.

cc @davidtwco, @wesleywiser

rustbot · 2025-04-14T22:50:20Z

This PR modifies run-make tests.

cc @jieyouxu

GuillaumeGomez · 2025-04-15T13:57:10Z

Finally fixed all tidy errors. :')

tshepang · 2025-04-26T10:24:05Z

src/librustdoc/config.rs

@@ -229,6 +229,22 @@ impl fmt::Debug for Options {
    }
 }

+#[derive(Clone, Debug)]
+pub(crate) enum PathOrURL {


Suggested change

pub(crate) enum PathOrURL {

pub(crate) enum PathOrUrl {

to follow idiom, and to be consistent with the style in this crate

bors · 2025-04-26T20:05:38Z

☔ The latest upstream changes (presumably #140336) made this pull request unmergeable. Please resolve the merge conflicts.

camelid · 2025-04-26T21:36:30Z

Whoops, missed this in my notifications, sorry 😅

It'll need an FCP before getting merged.

Any reason you're making it insta-stable? Seems like might as well go through the normal process of adding as an unstable flag first.

GuillaumeGomez · 2025-04-26T21:53:21Z

Any reason you're making it insta-stable? Seems like might as well go through the normal process of adding as an unstable flag first.

~~Oh damn, not insta-stable. Very good catch, thanks!~~

It was already unstable. 😄

GuillaumeGomez · 2025-04-26T22:26:25Z

src/librustdoc/lib.rs

@@ -658,6 +658,14 @@ fn opts() -> Vec<RustcOptGroup> {
            "disable the minification of CSS/JS files (perma-unstable, do not use with cached files)",
            "",
        ),
+        opt(
+            Unstable,


@camelid: Just checked and the option is indeed unstable. 😉

Ah, I was just confused because you said it'd need an FCP, which I thought we only required for stabilizations.

Hum, well it's a big change in rustdoc (as is, scope expansion), so better be sure everyone agrees with this direction.

camelid

Looks good overall, but left some comments.

camelid · 2025-05-06T02:52:52Z

src/librustdoc/config.rs

+#[derive(Clone, Debug)]
+pub(crate) enum PathOrURL {
+    Path(PathBuf),
+    URL(String),


Ditto here with tshepang's suggestion from above.

camelid · 2025-05-06T02:54:52Z

src/librustdoc/lib.rs

@@ -658,6 +658,14 @@ fn opts() -> Vec<RustcOptGroup> {
            "disable the minification of CSS/JS files (perma-unstable, do not use with cached files)",
            "",
        ),
+        opt(
+            Unstable,


Ah, I was just confused because you said it'd need an FCP, which I thought we only required for stabilizations.

camelid · 2025-05-06T03:00:02Z

src/librustdoc/lib.rs

+        Err(error) => return Err(format!("failed to load book: {error:?}")),
+    };
+    let output_dir = render_options.output.join("doc-book");
+    *book_dir = output_dir.join("index.html");


I don't like that this mutates the render_options.book_location to record the new path of the book. I think it'd better to have two separate fields, one for the source location of the book and one for the target location (None if the source was a URL).

Not sure to agree but not something I think is worth debating about so let's go. However: I'm gonna use PathOrUrl because otherwise you'd need to use two types to get the information, which is suboptimal imo.

camelid · 2025-05-06T03:01:12Z

src/tools/tidy/src/deps.rs

@@ -28,6 +28,7 @@ const LICENSES: &[&str] = &[
    "Apache-2.0",
    "Apache-2.0/MIT",
    "BSD-2-Clause OR Apache-2.0 OR MIT",                   // zerocopy
+    "CC0-1.0",                                             // notify


Who's responsible for this license exceptions list? Feels like it'd be good to check that these exceptions are OK with someone who's more experienced in this area.

I know the right person for this. cc @wesleywiser :)

camelid · 2025-05-06T03:02:27Z

tests/rustdoc/book-location.rs

@@ -0,0 +1,7 @@
+//@ compile-flags: -Zunstable-options --book-location https://somewhere.world


We should have another (run-make) test that tests the mdbook integration, especially since that's where most of the complexity of this PR is.

What do you want to test exactly?

camelid · 2025-05-06T03:04:08Z

src/doc/rustdoc/src/unstable-features.md

+## Generating link to guide
+
+You can generate a link to a guide or generate the guide with `mdbook` using the `--book-location`
+command line argument. It accepts either a URL or a path. If a path is provided, the book will
+be generated.


Suggested change

## Generating link to guide

You can generate a link to a guide or generate the guide with `mdbook` using the `--book-location`

command line argument. It accepts either a URL or a path. If a path is provided, the book will

be generated.

## Bundling or linking to a guide

You can generate a link to a guide or bundle an `mdbook` guide using the `--book-location`

command line argument. It accepts either a URL or a path. If a path is provided, the book will

be built with `mdbook`.

bors · 2025-05-07T05:18:53Z

☔ The latest upstream changes (presumably #140726) made this pull request unmergeable. Please resolve the merge conflicts.

…e the target location

GuillaumeGomez · 2025-05-07T14:55:46Z

Fixed merge conflict.

rustbot assigned camelid Apr 13, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the book-location branch from 15e7374 to 1aefb85 Compare April 14, 2025 09:49

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the book-location branch from 1aefb85 to bcb5ed2 Compare April 14, 2025 10:59

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the book-location branch from bcb5ed2 to cad5667 Compare April 14, 2025 11:56

rustbot added A-tidy Area: The tidy tool T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) labels Apr 14, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the book-location branch from cad5667 to 3388b0b Compare April 14, 2025 22:50

rustbot added the A-run-make Area: port run-make Makefiles to rmake.rs label Apr 14, 2025

tshepang reviewed Apr 26, 2025

View reviewed changes

GuillaumeGomez commented Apr 26, 2025

View reviewed changes

camelid reviewed May 6, 2025

View reviewed changes

GuillaumeGomez force-pushed the book-location branch from 3388b0b to d4fefe0 Compare May 6, 2025 14:18

This comment has been minimized.

Sign in to view

Add --book-location option to provide guide alongside documentation

9689b41

GuillaumeGomez added 4 commits May 7, 2025 16:55

Add documentation for --book-location option

6b03ce4

Add test for --book-location

245e31f

Add new licenses to tidy check

1cdcf58

Rename book_location into book_source and add a new field to stor…

eda5e44

…e the target location

GuillaumeGomez force-pushed the book-location branch from 7d007c9 to eda5e44 Compare May 7, 2025 14:55

This comment has been minimized.

Sign in to view

Ignore tidy file length for rustdoc.css

7e3df42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local #139769

[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local #139769

GuillaumeGomez commented Apr 13, 2025

rustbot commented Apr 13, 2025

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rustbot commented Apr 14, 2025

This comment has been minimized.

rustbot commented Apr 14, 2025

GuillaumeGomez commented Apr 15, 2025

tshepang Apr 26, 2025

bors commented Apr 26, 2025

camelid commented Apr 26, 2025

GuillaumeGomez commented Apr 26, 2025 •

edited

Loading

GuillaumeGomez Apr 26, 2025

camelid May 6, 2025

GuillaumeGomez May 6, 2025

camelid left a comment

camelid May 6, 2025

camelid May 6, 2025

camelid May 6, 2025

GuillaumeGomez May 6, 2025

camelid May 6, 2025

GuillaumeGomez May 6, 2025

camelid May 6, 2025

GuillaumeGomez May 6, 2025

camelid May 6, 2025

This comment has been minimized.

bors commented May 7, 2025

GuillaumeGomez commented May 7, 2025

This comment has been minimized.

		@@ -0,0 +1,7 @@
		//@ compile-flags: -Zunstable-options --book-location https://somewhere.world

[rustdoc] Add new --book-location option to add a link to associated guide and generate it if local #139769

Are you sure you want to change the base?

[rustdoc] Add new --book-location option to add a link to associated guide and generate it if local #139769

Conversation

GuillaumeGomez commented Apr 13, 2025

rustbot commented Apr 13, 2025

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rustbot commented Apr 14, 2025

This comment has been minimized.

rustbot commented Apr 14, 2025

GuillaumeGomez commented Apr 15, 2025

Choose a reason for hiding this comment

bors commented Apr 26, 2025

camelid commented Apr 26, 2025

GuillaumeGomez commented Apr 26, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camelid left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment has been minimized.

bors commented May 7, 2025

GuillaumeGomez commented May 7, 2025

This comment has been minimized.

[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local #139769

[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local #139769

GuillaumeGomez commented Apr 26, 2025 •

edited

Loading