Adding headers before a toctree causes it to disappear in the sidebar

[choldgraf]

If you put a header just before a toctree, then the toctree items no longer appear in the sidebar. For example:

.. toctree::

   mypage

works, but

My header
=========

.. toctree::

   mypage

causes mypage to not show up.

I think that this is because of this line:

https://github.com/pandas-dev/pydata-sphinx-theme/blob/3a538b1dbed9fed302c314765dda9b73a0b6ab85/pydata_sphinx_theme/__init__.py#L113

which is preventing us from discovering nested pages under the header list item.

I am a bit surprised that we have not run into this before. Do the pandas docs not use any headers on a page above the toctree? I just discovered that it was the case in some jupyter docs and I just didn't notice, so @jorisvandenbossche you may want to check.

[choldgraf]

I have one sort-of fix for this here: #219

[mattip]

We hit this in numpy as well: this page is not showing the toctree

[choldgraf]

yeah, this is going to be a problem until we resolve this bug or #219 is merged. In the meantime in Jupyter we are just including a :hidden: toctree at the top of every page, to make sure that the elements show up in the sidebar 🤷

[mattip]

In the case I mentioned above, we wanted the toctree to show up at the bottom of the document, not the top. Is there a convenient trick in sphinx RST to duplicate the toctree as a hidden element at the top of the page?

[choldgraf]

yeah that's what I mean, we put :hidden: at the top, and then any toctrees we want to actually show up we put throughout the page like normal. E.g.: https://raw.githubusercontent.com/jupyter/jupyter/master/docs/source/use/using.rst

[mattip]

Thanks, I will adopt the TODO comment.

[eric-wieser]

we wanted the toctree to show up at the bottom of the document, not the top

I think I have an open PR against Sphinx for this... Will link it when I get around to it.

[mattip]

Did you mean sphinx-doc/sphinx#3622?