rustdoc: "Namespace" user-written Markdown headings

[camelid]

View all comments

Tracking issue for @jsha's idea mentioned here. What follows is @jsha's summary of the idea:

When markdown like # Examples is processed, it usually turns into something like <a href="#examples" id="examples">. This is useful so you can click on the heading and get a link that will take someone else to that precise part of the docs.

Since the markdown in rustdoc is user-generated, those anchor ids may conflict with Rustdoc's own anchor ids. They may also conflict with other markdown sections within the same doc page. For instance, see:

https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples
https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples-1
https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples-2

Right now we disambiguate these ids by added a number at the end. However, it would be better to disambiguate them by namespacing. Specifically, each time we render markdown we should provide a "prefix", and all IDs in the generated HTML should start with that prefix. In general a convenient and sensible choice for this prefix would be the id of the immediately preceding heading. So the examples linked above might become #top.examples, #method.new.examples, and #method.from_utf8.examples.

This has three advantages:

• It systematically removes most of the cases of id conflict.
• It makes anchor links more meaningful when someone reads the URL.
• It makes anchor links stable across revisions.

This is a 99% solution, not a 100% one. Users can author HTML directly in their markdown, for instance <div id="foo">. But we are okay with letting the conflicts happen in those rare cases.

[GuillaumeGomez]

I'll work on this.

[camelid]

@rfcbot fcp merge

Overall, I'm in favor of this idea; however, I'd still like to have a discussion about breakage before we merge in.

See #92043 (comment) for my concerns.

[rfcbot]

@camelid has proposed to merge this. The next step is review by the rest of the tagged team members:

• @CraftSpider
• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @camelid
• @jsha
• @jyn514
• @ollie27

Concerns:

• anchor formatting resolved by rustdoc: "Namespace" user-written Markdown headings #91759 (comment)
• breakage resolved by rustdoc: "Namespace" user-written Markdown headings #91759 (comment)
• impls resolved by rustdoc: "Namespace" user-written Markdown headings #91759 (comment)
• simplify (rustdoc: "Namespace" user-written Markdown headings #91759 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[camelid]

@rfcbot concern breakage

I'd like to discuss this and for us to all be on the same page before this is merged.

[camelid]

@rfcbot concern impls

I think we need to namespace by impl too.

For example, the primitive.pointer.html page has impls for both *const T and *mut T. The methods on each are currently disambiguated using the number suffixes (cc @scottmcm who ran into issues with this), but after this change, I think they would conflict. IIUC, the current implementation in #92043 only namespaces by the parent item (e.g., method name), but what about when there are two impls on a page with the same method names?

Note that this occurs for some user types too, not just the pointer page.

[jsha]

Good point. Here's a concrete example:

https://doc.rust-lang.org/nightly/std/any/trait.Any.html#examples-7
https://doc.rust-lang.org/nightly/std/any/trait.Any.html#examples-2

Those are the examples section for <dyn Any + 'static>::downcast_ref and <dyn Any + Send + 'static>::downcast_ref, respectively.

The links to those impls themselves have the same "incrementing number" problem: https://doc.rust-lang.org/nightly/std/any/trait.Any.html#impl and https://doc.rust-lang.org/nightly/std/any/trait.Any.html#impl-1. So it would be good to fix that at the same time we fix this.

For instance, we might make the link to the first impl #impl.dyn-any-static, and the second #impl.dyn-any-send-static. Then the examples sections could be #impl.dyn-any-static.method.downcast_ref.examples or similar.

Note: there is prior art for certain impls getting an anchor that reflects their type parameters. For instance see https://doc.rust-lang.org/nightly/std/string/struct.String.html#impl-Add%3C%26%27_%20str%3E.

This happens in the "Implementations" section of a struct page. It doesn't happen in the "Implementors" section of a trait page.

Note that the String anchor linked above is over-encoded. If we wind up tweaking generation of impl targets I'd like something with the right level of encoding. See this demo.

<a id="impl-Add<&'_ str>" href="#impl-Add%3C&'_ str%3E">target</a>

[camelid]

I agree with what you say, but I mean that headings within methods within impls need to be namespaced like #impl-Add.method.add.examples. My understanding (I may be incorrect) of Guillaume's current PR is that it would create the fragment #method.add.examples, which would conflict with other impls of Add.

[jsha]

Yep, we're on the same page - I was intending to agree and expand. In order to fix the conflict between same-named methods, we need to namespace by impl plus method name; that in turn brings up the parallel issue that id assignment for impls has a very similar problem, and we should fix both at once.