search

nextstrain / sphinx-theme

A Sphinx theme for Nextstrain's documentation, based on Read The Docs' default theme.
https://docs.nextstrain.org/projects/sphinx-theme/
MIT License
0 stars 5 forks source link

toctree section headers (without index pages) #8

Open eharkins opened 3 years ago

eharkins commented 3 years ago

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: https://github.com/nextstrain/ncov/pull/709#issuecomment-904961475.

jameshadfield commented 3 years ago

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 https://github.com/nextstrain/docs.nextstrain.org/commit/7533335cf54266f810c347b9b2ab360e3417d090 ?

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.

image
tsibley commented 2 years ago

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.