Make documentation more browsable with ToC

[hyamanieu]

Problem statement

It concerns all holoviz projects but I'm posting here as I believe holoviews is the core project. I spend a considerable amount of time on various holoviz documentations (hvplot, holoviews and panel). Navigating on each is not simple as a table of content is lacking.

Describe the solution you'd like

Bokeh's documentation has a flying table of content. This would be the best solution to me.

Describe alternatives you've considered

A non flying table of content would also simplify browsing the documentation.

Additional context

See e.g. https://docs.bokeh.org/en/latest/docs/user_guide/data.html#userguide-data with the flying ToC.

[jlstevens]

I agree there should be a nice table of contents somewhere in the docs to help with navigation.

[ppwadhwa]

I'd prefer a TOC on the side if its a full TOC. To me, that is more out of the way and can hold more information. Looking at Bokeh's example, it looks like sections (rather than a full TOC) are listed at the top that stay in place as you scroll. This isn't bad either for a quick way to access different sections.

[hyamanieu]

On a desktop using Firefox, Bokeh's TOC is on the side (or perhaps I misunderstood you).
Besides upon reaching a specific section, its subsections appear and other subsections disappear so the TOC is not cluttered yet exhaustive.

[ppwadhwa]

Great, I will look more closely! I agree that having a convenient way to navigate to different sections would be very useful.

[jbednar]

I'm confused; I don't see any clear difference between Bokeh's TOC:

and HoloViews' existing TOC:

[hyamanieu]

James,
the "flying" toc is on the right hand side. It's the webpage ToC, not the website Toc.

Not sure which browser/machine you're using, but below 1200px width the flying ToC indeed disappears.

[jbednar]

Ah, yes, I browse docs on a portrait-orientation monitor and Bokeh's flying TOC isn't shown in my configuration. I'm still confused, though, as your original issue description asks for a flying TOC but also says that "A non flying table of content would also simplify browsing the documentation." These sites already have a non-flying TOC, so I'm unsure what potential simplification you're referring to here.

Was that just confusingly stated, and the real request is then "I would like to have a flying TOC for HoloViz docs pages to help me better navigate within each page" (given that the overall site navigation is already covered by the TOC on the left site)?

[hyamanieu]

There is no ToC of webpages (there is for the whole site though). Composing Elements for example has 4 h2 header and 6 h3 headers. Having a ToC with these headers would greatly help.
I am not a web developer, but I guess there are libraries which automatically generate it as is done within Jupyter with the ToC add-on?

[jbednar]

If you just want those subheadings to show up on the TOC on the left, I believe that's as simple as changing the tocdepth on the sphinx doc configuration. So is that the specific request here, i.e. either a flying toc for navigating the subheadings on the page, or to change the tocdepth for HoloViz projects to include at least top-level headings and not just separate pages?

[hyamanieu]

I can see this flying webpage ToC on the right hand side was included in three different parts of the sphinx documentation in Bokeh (id is bd-toc-nav) https://github.com/search?q=org%3Abokeh+bd-toc-nav&type=code
(The id for the website ToC on the left hand side is bd-docs-nav.)
However not sure how/where it is configured. Perhaps @bryevdv could point us in the right direction?

My request is rather:

• (1) either have the web page ToC on the right hand side flying. This may mean to take out the message regarding the non-interactivity of auto generated notebooks which is exactly located where I would see this ToC. I believe this message is less important than a ToC, it could be a simple note at the top of a page.
• (2) or have a fixed one at the top of the web page if it's easier. It's already helping a lot with long pages.

In both cases I would leave the web site ToC unchanged.

Of course if the h2 headers appear on the left hand side ToC as subsections (3), it's already an improvement to me. I can understand it's the simplest way to go if it's only about changing a parameter like tocdepth.

[bryevdv]

All I can note is that Bokeh uses a customized vendored version of the "pydata" sphinx theme:

https://github.com/pydata/pydata-sphinx-theme

Customized and vendored because we were very early adopters and it was missing some features we needed at the time. But it's had lots of work and updates since then and we are meaning to move over to the official theme package soon.

[hyamanieu]

I wanted to see what I could do. But the doc Makefile includes another Makefile that disappeared in a 2014 commit. Not sure where to go from there.

[jbednar]

We aren't using any makefiles that I'm aware of, so presumably that's just hanging around (though I'd be reluctant to delete it without checking!). The steps for building docs are listed in .github/workflows/docs.yml.

[jbednar]

This may mean to take out the message regarding the non-interactivity of auto generated notebooks which is exactly located where I would see this ToC. I believe this message is less important than a ToC, it could be a simple note at the top of a page.

We've previously had this note at the top of pages, and people kept missing it. They would go to a certain spot in the page that looked interesting, play with the example and then report that the example was broken (or, worse, assume the tool was buggy and give up on it). We definitely need a flying warning like that on any pages that have content that works in a notebook or server context but not on a web page. It's conceptually fine to combine that note with a flying TOC, but I don't know how that would work at the code level.

[hyamanieu]

Moved to https://github.com/pyviz-dev/sphinx_holoviz_theme/issues/17

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.