ENH: support toctree captions as first navigation level?

[jorisvandenbossche]

Ah damn, run into an issue. In the top level documentation we use multiple toctree`s with captions to structure the sections. This is fine in RTD, but pydata-sphinx-theme doesn't take these captions into account when constructing the top bar:

• Source: https://github.com/aiidateam/aiida-core/blob/develop/docs/source/index.rst
• RTD: https://130-77234579-gh.circle-artifacts.com/0/html/index.html
• pydata: https://132-77234579-gh.circle-artifacts.com/0/html/index.html

@jorisvandenbossche any quick fix you can think of, or shall I raise a separate issue? I reckon pydata-sphinx should be able to handle this in some way, since I don't think it's an uncommon practice.

The only other minor difference, is that RTD shows the documentation version at the top-right. I'm not sure if that is strictly necessary. But it might be nice to have the option to show this in some fashion

Originally posted by @chrisjsewell in https://github.com/pandas-dev/pydata-sphinx-theme/issues/188#issuecomment-635871957

[jorisvandenbossche]

In the top level documentation we use multiple toctree`s with captions to structure the sections. This is fine in RTD, but pydata-sphinx-theme doesn't take these captions into account when constructing the top bar

@chrisjsewell Yeah, that's a known issue, and @choldgraf looked at this before, and I was recently trying to pick it up again, see https://github.com/pandas-dev/pydata-sphinx-theme/pull/135

It's indeed something we should handle, as it is commonly used.

Now, in your case, I think you want to use those captions as the "first level of navigation", right? So to use those items for the top navbar? (the PR I linked too is more about allowing those captions in the sidebar)

[jorisvandenbossche]

So this theme uses the toctree as inferred by sphinx from your project (but ignoring captions at the moment ..) to structure the layout.

That also means that you might need to structure your sphinx doc directory layout (or the toctrees) in such a way that it fits what you want to see in the html docs.

Meaning that you need nested toctrees (not necessarily a nested directory layout, as sphinx just looks at the toctree directives). While in your example of AIIDA, you have single flat toctree (just split in separate toctree directives with a caption, but for sphinx that's basically a single flat level)

[chrisjsewell]

Yeh, it is a bit of a weird one, because there is technically nothing to actually link to for the captions. I had the same issue with the panel links, where I am currently just linking to the first document in each section.

Meaning that you need nested toctrees (not necessarily a nested directory layout, as sphinx just looks at the toctree directives)

yeh I might have a play around with this quickly

[chrisjsewell]

I have to say, I do prefer the RTD toctree bar though, where you can quickly link to anywhere in the documentation (to depth 2), e.g. in https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html, it feels a bit redundant that there is a blank toc bar, and you are having to instead have the toctree show on the page

[jorisvandenbossche]

I commented on https://github.com/aiidateam/aiida-core/pull/4129, I think it would actually not be a big change to get it working with the current release.

One thing is that you indeed get those "ugly" landing pages with only the toctree, while it would be nice to directly go to for example the first subpage (eg in pandas this page is quite useless: https://pandas.pydata.org/docs/user_guide/index.html, for the getting started index.rst, we added some more content which makes this approach OK: https://pandas.pydata.org/docs/getting_started/index.html. But you might not necessarily have such content for each index.rst ..)

Related issue: https://github.com/pandas-dev/pydata-sphinx-theme/issues/60

[jorisvandenbossche]

I have to say, I do prefer the RTD toctree bar though, where you can quickly link to anywhere in the documentation (to depth 2),

Then you might want to use the "single level" version of this theme instead? (without the top navbar) See https://github.com/pandas-dev/pydata-sphinx-theme/issues/90. This version doesn't exist yet in this repo, but basically is the sphinx-book-theme, or a slight variation on the layout of this theme like in eg https://contextily.readthedocs.io/en/latest/ (only that we want caption support there, which sphinx-book-theme already does, which is for you certainly a reason to use that). I would personally still like to see this "no-top-bar-layout" included in this repo as well, but that's a discussion for https://github.com/pandas-dev/pydata-sphinx-theme/issues/90

e.g. in https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html, it feels a bit redundant that there is a blank toc bar, and you are having to instead have the toctree show on the page

Yes, for home pages, that's certainly a problem that should be solved. One way is to add more content to the home page (and hide the in-page toctree), but you might also want a different layout for the home page (eg no left sidebar), see https://github.com/pandas-dev/pydata-sphinx-theme/issues/146

[chrisjsewell]

I guess essentially what I'd like is the bulk of the pydata theme, but with the "fixed" left toctree from the RTD theme. At least for the amount/depth of content in the AiiDA documentation, I think it's a lot more user-friendly that you can scan down the left ToC to get a good/quick outline of the documentation and quickly select e.g. Topics/Workflows, rather than having this extra step of having to first navigate to Topics then looking what's there.

[jorisvandenbossche]

What do you understand exactly under "the bulk" ?

Also the top navbar? I would assume not, since that would then duplicate the captions of the left sidebar toctrees ? And if you want everything except the top navbar, isn't that basically the "single level" version what I mentioned before (so basically something like https://jupyterbook.org/intro.html or like https://contextily.readthedocs.io/en/latest/ (but with captions in the sidebar))

At least for the amount/depth of content in the AiiDA documentation

Yes, it certainly depends on the amount of links that are in the left sidebar whether it becomes beneficial to splitting this up into "first level nav in topbar and second+ level navigation in sidebar", or whether you prefer keeping all levels of navigation in the sidebar.

It's mainly when the number of links / pages in the sidebar get that big that you need to do a lot of scrolling in it that I personally prefer moving part of the navigation to the top navbar, but of course that is still subjective ;)

[chrisjsewell]

Sorry this is mainly just me thinking out loud... I think the top banner works better as part of a larger website, where your "documentation" is a section of the overall site, like:

pandas and AiiDA are both a bit similar in this respect, in that they actually have separate top-level and documentation sites:

• https://pandas.pydata.org/ and https://pandas.pydata.org/docs/
• http://www.aiida.net/ and https://aiida.readthedocs.io

Its kind of odd for both that clicking on the documentation section of the banner on the main site leads you to a completely different site, with its own separate layout.

[chrisjsewell]

What do you understand exactly under "the bulk" ?

I guess just the general CSS, plus the right "page level" ToC

[chrisjsewell]

BTW I was recently pointed toward this "search as you type" extension https://readthedocs-sphinx-search.readthedocs.io which is pretty nice. I haven't check yet if it works already with the pydata theme, but it might be a consideration to include/embed it or something similar by default.

[choldgraf]

since we're talking about RTD-only extensions, there's also this nifty extension to provide hover tooltips: https://pypi.org/project/sphinx-hoverxref/

[chrisjsewell]

nice!

[choldgraf]

@chrisjsewell yeah, I am hoping we can convince RTD to special-case jupyter books so that people can use these extensions in their books if they use RTD...

[chrisjsewell]

convince RTD to special-case jupyter books

What do you mean by special case?

[choldgraf]

right now RTD only supports "regular" sphinx builds, mkdocs, and maybe one or two other documentation engines. Since Jupyter Book builds books with jupyter-book build mybook/ rather than make html w/ Sphinx, then we need RTD to support this build command. (unless you know of a way to use custom build commands with RTD?)

[chrisjsewell]

unless you know of a way to use custom build commands with RTD?

Yeh not that I know, so sounds like a good idea

[12rambau]

This issue has no activity since 2020 is it still a wanted feature ?

[trallard]

Since there has not been a follow-up and this issue seems stale anyway, I will go ahead and close it. If there is need for this at a later time we can re-open this issue.