rustdoc: Add anchors to section headers

[alexcrichton]

This commit adds a appear-on-over link to all section headers to generated
documentation. Each header also receives an id now, even those generated through
markdown. The purpose of this is to provide easy to link to sections.

This modifies the default header markdown generation because the default id
added looks like "toc_NN" which is difficult to reconcile among all sections (by
default each section gets a "toc_0" id), and it's also not very descriptive of
where you're going.

This chooses to adopt the github-style anchors by taking the contents of the
title and hyphen-separating them (after lower casing).

Closes #12681

[alexcrichton]

preview: http://www.contrib.andrew.cmu.edu/~acrichto/doc/std/index.html

[adrientetar]

Is the yellow highlight necessary? I don't think it serves any purpose and it adds visual noise imo. Looks good otherwise.

[alexcrichton]

It was initially implemented for jumping to methods and such because it's quite a forest once you get into the nitty gritty. That may be a little different from this, but I kinda like the highlights (not that I have a designer license any more)

[huonw]

What happens with something like

# General Topic 1

## Example

# General Topic 2

## Example

Do both Examples get the example anchor?

[alexcrichton]

@huonw, good catch. I think I'll again adopt what github does and name the second one example-2 whereas the first one is just example

[huonw]

Expanding on that example above, AFAICT each markdown chunk is rendered in isolation via a Show impl, but there are some pages that show multiple independent chunks (e.g. trait pages, and pages for types with docs on each method).

These should have unique anchors too: I guess just adding the current method/function/whatever to the subsection would work (e.g. #method.foo-example for the Example heading in the docs of a fn foo(&self))... but this presumably requires external state which rendering via Show doesn't support easily.

[huonw]

Oh, I guess one could just put the parent information into the markdown struct itself via a parent: Option<&str> field. Breaks the neatness of Markdown<'a>(&'a str) though. :(

[alexcrichton]

Updated with a task-local map which is reset across page boundaries.

[huonw]

Couldn't this be

match map.find_mut(&id) {
    None => {}
    Some(a) => { *a += 1; format!("{}-{}", id, a - 1); return }
}
map.insert(id.clone(), 1);

?

(Not that performance matters much here.)

[alexcrichton]

Looks cleaner to me!

[huonw]

I'm not keen on having the implicit almost-global (especially if this part of rustdoc is ever parallised, but I guess this is unlikely to happen, since markdown rendering is now really fast since we're not shelling out to pandoc, right?), but it is certainly a neat solution to this.

[alexcrichton]

I think this strategy would work with parallelism because we'll only ever parallelize on the granularity of rendering pages, not rendering within a page itself (we generate a huge number of pages).

[alexcrichton]

Updated with comments