toctree section headers (without index pages)

[eharkins]

As @jameshadfield put it here:

I really want section headings (e.g. "Analysis" or "Getting started with analysis") to be simply headings in the sidebar, not pages in and of themselves. This holds for all our documentation on RTD, where we often have to create dummy pages with no real content.

According to @tsibley, this is possible: nextstrain/ncov#709 (comment).

[jameshadfield]

This issue has been addressed partially addressed for the main docs project but not yet for the subprojects (e.g. ncov). @tsibley was this achieved by nextstrain/docs.nextstrain.org@7533335 ?

Top level section headers (e.g. "HOW TO GUIDES" in the screenshot) are now simply headings for their respective contents, however section headings one level deeper (e.g. "Bioinformatics") are still pages. In my ideal world, clicking "bioinformatics" would behave the same as clicking the "+" icon and result in expansion of pages underneath that (sub-)heading without loading a separate docs page.

[tsibley]

Yeah, I hear you about the ideal. Going arbitrary levels deep like that isn't provided for by the RTD Sphinx theme. There's two things I see that we could do here:

1. Implement the desired sidebar behaviour ourselves by modifying the RTD navigation JS, with the knowledge that it'll be a divergence from both that as well as the way Sphinx models document hierarchies.

2. Accept the behaviour as good enough and leave it as-is, but instead of making section index pages like "Bioinformatics" a "dummy page with no real content", we could add actual content. :-) I think it'd be very useful to include explanatory material on index pages that discuss the topic and frame the subpages for a reader. We do this already to some degree on the "Sharing analyses" index page, for example.