List page headers / table of contents in-text

[choldgraf]

When you have a page with multiple headers (especially nested ones), it is useful to be able to list each header with a link throughout the page. This is different from the sidebar contents list, because it flows within the text and often only points to a subset of headers.

This is particularly useful when you have a large page and specific sub-sections can get lost within the page-wide contents list, and so you want to define a short list of a section's headers in order to orient the user.

For example, given a document like this:

# Types of things

```{tableofcontents} Things in this section
```
## Type 1

Foo

## Type 2

Bar

## Type 3

Baz

It would output something like:

Types of things

**Headers in this section**
- [Type 1](link)
- [Type 2](link)
- [Type 3](link)

**Type 1**

Foo

**Type 2**

Bar

**Type 3**

Baz

Implementations

Sphinx has two ways of doing this:

• toctree is how you define the structure of a book, and also results in a list of toctree items in the page content (wherever the toctree was placed).
• contents is a docutils directive that lists the content headers for the current section.

Converting this into an issue since it was a draft issue on our board