Use appropriate heading levels in docblocks

[jsha]

Following up on #87059 (big thanks @ahicks92 for the detailed feedback!):

[...] Rustdoc didn't do h tags right. It's not exactly systemic, but it's something like (level + 3) % 6, where what should be heading levels 4-6 (examples, etc) become heading level 1 and 2. This is confusing, but once you learn things like impl blocks tend to be heading level 3 and functions are usually level 4, you effectively have a "jump to next function" keystroke and so on.

Here's what's happening: in Markdown # generally represents an h1, ## represents h2, and so on. That means each docblock often has h1s and h2s in them, even though they are nested under higher-up h1s and h2s. For instance, https://doc.rust-lang.org/1.55.0/std/io/trait.Read.html has an <h1>Trait std::io::Read</h1> and an <h1>Examples</h1>. The latter should be <h2>. Similarly, there's an <h4>fn read...</h4>, with an <h1>Errors</h1> nested under it. The latter should be <h5>.

Per https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#usage_notes:

Avoid skipping heading levels: always start from <h1>, followed by <h2> and so on.
Use only one <h1> per page or view. It should concisely describe the overall purpose of the content.

Fortunately, we already control the <h{level}> tag that's emitted based on Markdown. The code is here:

rust/src/librustdoc/html/markdown.rs

Lines 535 to 540 in 2b6ed3b

	let start_tags = format!(
	"<h{level} id=\"{id}\" class=\"section-header\">\
	<a href=\"#{id}\">",
	id = id,
	level = level
	);

. What we additionally need:

• Add a way to keep track of what heading level we're generating Markdown into: are we nested under an <h1> or under an <h4>?
• Adjust the {level} interpolation to add the number of levels appropriate. This should be capped at 6, since h6 is the highest defined in HTML.
• Adjust CSS styles appropriately.

[ahicks92]

Cool. I'm still around if I can be of assistance.

[yaymukund]

Interesting. Thank you for the detailed description of the issue.

I'd like to give this a shot in the upcoming week, assuming that time-frame is good and nobody's already claimed it :)

[jsha]

That time frame is good, and nobody's claimed this. Thanks for working on it! Feel free to ask questions if you run into any problems.

[yaymukund]

If you want to try this out, this should now be fixed in the nightly docs. For example, here's the Read trait:

https://doc.rust-lang.org/nightly/std/io/trait.Read.html

[jsha]

Well done @yaymukund, thank you! @ahicks92 if you have time I'd love your input on whether this fixes the issue and whether there are still things to be improved.

[ahicks92]

It's better, and I think this is sufficient. But I'll throw out two oddities:

• The first heading on the page is h2, and reads almost identical to the h1 heading (put another way it's not immediately clear that you're in a table of contents); and
• We have jumps in the heading level, e.g. "Required methods" is h2, then fn read(&mut self, buf: &mut [u8]) -> Result<usize> is h4.

I'm calling them oddities and not bugs/blockers because in practice this is probably at the 95th percentile when it comes to me trying to think of sites that don't get this wrong and do it well, and I'd expect anyone to be able to work it out after a bit. But it might still be worth smoothing out at some point anyway if someone ends up with the time.