Consider alternative navigation for Examples within ReadtheDocs

[brendanreardon]

Pull Request #229 added all examples to the latest branch of our ReadtheDocs. Each example has its own page now, with an index that lists examples by Constraint. This is currently manually constructed.

As of this writing there are 20 example Categorical Variants in the repository and, if we went with the usual approach for how navigation works in ReadtheDocs, the "Examples" sub item in the side bar would be quite long relative to other menu selections. We thus made a design decision to make each example an orphan page so that they will not appear in the side bar when within the Examples part of the site.

Here, I'll outline a few potential approaches to this and include screenshots of what they would look like. We would love your feedback on which approach you prefer, or if you have any alternative ideas. This component of the documentation will be moved into the 1.0 branch eventually.

The approaches that we've thought of are:

• What we went with: Specify each example as an orphan page. Individual examples do not appear in the sidebar navigation.
• What the default would have been: Each example is not marked as an orphan and all examples appear in the side navigation.
• An alternative: Overwrite the ReadtheDocs template for breadcrumb navigation.

I'll create a comment for each approach. Thank you!

[brendanreardon]

What we went with: Specify each example as an orphan page. Individual examples do not appear in the sidebar navigation. Example pages do not have breadcrumb navigation, so we included a hyperlink back to the examples index at the top one each page.

Pro: Side navigation remains minimal.

Con: No breadcrumb navigation at the top on each page. Instead of "(home icon) / Examples / (example name)", the navigation on the top is just "(home icon) / (example name)".

[brendanreardon]

What the default would have been: Each example is not marked as an orphan and all examples appear in the side navigation.

Pro: Breadcrumb navigation at the top of each example's page is fully intact.

Con: The sidebar navigation under Examples exhaustively lists all examples.

Only a subset of examples are shown in the side navigation within this screenshot.

[brendanreardon]

An alternative: Overwrite the ReadtheDocs template for breadcrumb navigation.

By inserting a near-identical .html file to what Sphinx uses for breadcrumb navigation, we can make sure that the bread crumb navigation always is shown based on folder structure that .rst files live in.

Pro: Sidebar navigation remains minimal, breadcrumb navigation remains.

Con: This may cause a complication in the future as the ReadtheDocs site is developed. Future maintainers may not know that the default breadcrumbs navigation behavior is being overwritten. To implement this approach, place breadcrumbs.html (attached) into docs/source/templates/.

breadcrumbs.html