Ref Docs need sidebar TOC

[bryevdv]

Consider this page, for instance:

https://docs.bokeh.org/en/2.0.2/docs/reference/models/annotations.html

There is no way to just load that page and know what annotations are documented there. Search is great if you know what you are looking for, but it you need to find out what annotations are available to begin with that page is very unhelpful. This is especially true now after adding inherited members to all models for completeness.

Including subsection headers in between classes would probably automatically afford a sidebar TOC if it can be done in an automated way.

[CapTen101]

Hi @bryevdv Can I take this? I saw the annotations page and yes I agree with you. There's no sub-tree to help take a look what's in the page. User who is just here to explore will certainly feel lost in the page.

[bryevdv]

@CapTen101 Certainly but I should mention I took a look this week and it may not be as simple as I had hoped. I though perhaps just adding a .. contents:: directive at the top would work but that is not sufficient. Probably not surprising since the automodule, etc directives are below. So it will take some investigation to figure out a way to add this in an automated fashion (my main requirement is that it be automatic and not every require any manual tinkering or updates later). It's maybe possible the theme or toctree could be modified to show the right sidebar that e.g. the user guide pages have.

[CapTen101]

I see @bryevdv. Right, I'll do some research about it and text you back as soon as I find any solution/workaround 👍

[santos22]

I was messing around with the autosummary Sphinx extension and found it kind of provides a TOC experience similar to the navigation sidebar. Using this extension generates a summary of classes, methods, and attributes near the top of a page. Clicking on each link takes you to the page/section of the page where you can see the docstrings.

I copied some of the Bokeh client code and published a small Sphinx site to showcase the extension (can remove if this violates the Bokeh license):
https://bokeh-toc.readthedocs.io/en/latest/

Source code:
https://github.com/santos22/bokeh-toc

Pros:

• provides TOC experience
• automatically generates boilerplate Sphinx documentation

Cons:

• changes the entire structure of existing documentation
• unsure if usage of this extension can be done in an "automated fashion"
• less flexible when documenting modules

[bryevdv]

In general I have never been a huge fan of autosummary I just feel like the output it generates is not great. Perhaps its more configurable now, though. A real test of its feasibility would involve generating docs for all the specialty Bokeh things like Models and their properties, i.e. how well does auto-summary play with our own important autodoc extensions.

[bryevdv]

The pydata sphinx theme now supports this as a built-in configuration, so we can make this happen along with #10685