[rustdoc] Add new `--book-location` option to add a link to associated guide and generate it if local by GuillaumeGomez · Pull Request #139769 · rust-lang/rust

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

 }

+#[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

            "",
        ),
+        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

            "",
        ),
+        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

    "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.

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

Fixed merge conflict.

bors · 2025-05-10T10:09:27Z

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

…e the target location

GuillaumeGomez · 2025-05-10T11:23:56Z

Fixed merge conflict.

bors · 2025-05-10T21:30:09Z

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

GuillaumeGomez · 2025-05-10T21:36:16Z

I think I'm gonna wait for the PR to be approved before fixing more merge conflicts. 😆

alice-i-cecile · 2025-05-10T23:30:10Z

Oh neat, Bevy will use this once it's shipped.

GuillaumeGomez · 2025-05-16T12:35:51Z

From discussion: remove the possibility to provide a URL, only allow a path (to ensure that once generated on docs.rs, versioning will always be valid).

BD103 · 2025-05-16T13:02:53Z

Oops, I just saw rust-lang/docs.rs#1293. If https://docs.rs can host mdbooks, then that solves all of my arguments. My bad! ^^'

GuillaumeGomez · 2025-05-16T13:05:05Z

It's path to file, not path to module.

notriddle · 2025-06-28T16:05:20Z

I'm not sure this feature has a plausible path to stability. mdBook occasionally releases breaking changes, has more breaking changes planned, does customization by directly replacing chunks of the HTML (which means every change to the DOM is breaking), and exposes fontawesome (which is on version 6.0) as part of its format.

IMO, the Rustdoc side of this feature needs to have a stability story more like how incompatible versions of a single Cargo library can coexist. Instead of incorporating mdBook's API into our own, crate authors should be able to pin the mdBook version without pinning the entire Rust toolchain.

A path like this one would also allow mdBook's stability story to be less extreme than Rust's and more like ammonia's: when 2.0 is released, 1.0 continues to receive security fixes, but no new features.

Other doc hosts, like ReadTheDocs and arXiv, pin the old version of their docs toolchains for exactly this reason.

Kixunil · 2025-07-02T13:33:49Z

@notriddle pinning doesn't sound too bad but maybe just having a minimal set of features would already help a lot? I think most books mainly need:

a way to have multiple pages
basic formatting: headings, bold, italic...
Rust and toml code examples as well as plaintext
for each page to be able to link to the doc items (crate::Foo)

Basically what rusdoc already has.

I personally find customization to be somewhat of an anti-feature - I want the docs to look consistent with rustdoc and not mess with it.

notriddle · 2025-08-27T19:17:56Z

@Kixunil I'm not sure if enough books would be satisfied with that to make it worth doing. That's the functionality that everybody uses, sure, but there's a "long tail" of features that, individually, most books don't need, but all together, most books need at least one thing that we don't have built-in.

@alice-i-cecile I don't know if "bevy will use this" means migrating that examples page into mdBook¹, but if it does, "20% functionality for 80% of books" won't cut it. There's a lot of stuff in there that mdBook doesn't do and won't add because most books don't need it.

Other books also wind up implementing a bunch of their own, non-overlapping, functionality. TRPL has a custom graphic for non-compiling examples, comprehensive-rust has a custom gizmo for "speaker notes", and rust-by-example has a language picker. Some of those might be worth baking in, but all of them?

I think Bevy uses Zola right now? ↩

alice-i-cecile · 2025-08-28T02:10:02Z

Yeah, I don't expect Bevy will migrate to mdBook: our needs are too complex for it to be a good fit for either party. Instead, we would just codify a URL link to our existing Zola-based web book.

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

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

GuillaumeGomez added 6 commits May 10, 2025 13:23

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

b90eb4a

Add documentation for --book-location option

ee49e83

Add test for --book-location

1d89078

Add new licenses to tidy check

d265210

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

5194f73

…e the target location

Ignore tidy file length for rustdoc.css

d0f941f

GuillaumeGomez force-pushed the book-location branch from 7e3df42 to d0f941f Compare May 10, 2025 11:23

syphar mentioned this pull request May 16, 2025

Add support for building and hosting mdBook content rust-lang/docs.rs#1293

Open

This comment was marked as outdated.

Sign in to view

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

Uh oh!

Conversation

GuillaumeGomez commented Apr 13, 2025

Uh oh!

rustbot commented Apr 13, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rustbot commented Apr 14, 2025

Uh oh!

This comment has been minimized.

rustbot commented Apr 14, 2025

Uh oh!

GuillaumeGomez commented Apr 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bors commented Apr 26, 2025

Uh oh!

camelid commented Apr 26, 2025

Uh oh!

GuillaumeGomez commented Apr 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

bors commented May 7, 2025

Uh oh!

GuillaumeGomez commented May 7, 2025

Uh oh!

This comment has been minimized.

bors commented May 10, 2025

Uh oh!

GuillaumeGomez commented May 10, 2025

Uh oh!

bors commented May 10, 2025

Uh oh!

GuillaumeGomez commented May 10, 2025

Uh oh!

alice-i-cecile commented May 10, 2025

Uh oh!

GuillaumeGomez commented May 16, 2025

Uh oh!

This comment was marked as outdated.

BD103 commented May 16, 2025

Uh oh!

GuillaumeGomez commented May 16, 2025

Uh oh!

notriddle commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kixunil commented Jul 2, 2025

Uh oh!

GuillaumeGomez commented Apr 26, 2025 •

edited

Loading

notriddle commented Jun 28, 2025 •

edited

Loading