Add breadcrumbs with links to parent pages in the article header

[choldgraf]

Many websites put "breadcrumbs" at the top of the page so that you can quickly see what parent pages are above you, and click through to them. For example:

The RTD theme:

The MDN docs:

What do folks think about using our article-header area to include breadcrumbs for each page? If we were worried about horizontal space, then we could restrict it to 2 parent pages, or limit the number of characters per header title or something.

[drammock]

I'm open to supporting this as long as it's optional / can be turned off in config. Are the intermediate levels in a breadcrumb guaranteed to exist though? (will there always be an index.html in every subfolder in _build/html/?) Off the top of my head, I'm not sure, but my guess is that it is not guaranteed by Sphinx.

[choldgraf]

I think the way you'd do it is by looping through a page's parent documents and using their titles + hrefs...those always do need to exist. So the folder structure in the filesystem wouldn't matter as much as the toctree structure of the documents

[trallard]

+1 on this one as this would help with navigation, especially if adding #1072

We should also consider how many levels will be displayed in the breadcrumbs or/and make this customisable. I think if there is a doc nested a few levels this might take too much space or would not fit the width at all

[choldgraf]

Fwiw, it looks very simple to implement. It is just this couple of lines in the RTD theme (assuming that the "parents" variable is built into sphinx)

https://github.com/readthedocs/sphinx_rtd_theme/blob/6444ca893043d8a0ca704474f7cf7d5a148f6767/sphinx_rtd_theme/breadcrumbs.html#L24