DOC: Switch docs to pydata-sphinx-theme

[rossbar]

NumPy recently switched to the pydata-sphinx-theme for its documentation. The new theme is now deployed for the stable docs as of v1.20. This PR switches the themes so numpydoc's documentation theme is consistent with numpy's.

[larsoner]

+1 for switching, let me know once CircleCI is happy and I should look

[rossbar]

Looks like the pydata-sphinx-theme relies on features (specifically, the override kwarg of set_translator) that aren't available before sphinx v1.8.

Is this a strong enough incentive to drop support for (or at least stop testing on) sphinx versions <1.8?

[larsoner]

Is this a strong enough incentive to drop support for (or at least stop testing on) sphinx versions <1.8?

Another option would be to run the pytest tests but not build the numpydoc docs on 1.8. 2.0 came out (a little bit) less than two years ago so it would be nice not to drop support for it yet.

[larsoner]

... oh 1.8 as the minimum, not 2.0. That seems okay to me.

[rossbar]

Okay, the minimum tested version has been bumped from 1.6.5 -> 1.8. I think this is ready for a review of the build artifact to see if there are any obvious problems from the theme switch. One thing I noticed is that pydata-sphinx-theme doesn't seem to make use of the html_title sphinx option, so the pages don't have the nice version tags (i.e. the numpydoc v1.2.dev0 Manual) anymore. I'm going to open a feature request upstream. Other than that, nothing jumped out to me.

[larsoner]

I don't really like how the left panel is not used. How about a structure more like either of these?

https://pandas.pydata.org/docs/getting_started/index.html
https://mne.tools/dev/overview/index.html

In other words, could the first-level bullets from under what is currently the "Documentation" become the options on the left? That way they will show up on every page, and make better use of the horizontal space, which is nice.

[rossbar]

I spent a little time on this and it turns out to be trickier than I was initially expecting.

AFAICT, the left sidebar is determined by the doc structure given by any .. toctree for each document, whereas the right sidebar is given by the heading structure within a single document. Since the the numpydoc documentation has a "flat" structure (i.e. only the index.rst has a toctree), the left sidebar for each page will always be blank. Since the sidebar will always be blank, I had hoped that I could remove it entirely so that the main page could use the full page width, but unfortunately it doesn't seem possible to completely get rid of the blank left column (see pydata/pydata-sphinx-theme#263).

My second thought was that I could swap the left sidebar (which is based on .. toctree) with the right sidebar (which is based on the internal doc structure from headings). This turned out to work - see 0fd8506. However, it relies on undocumented features in pydata-sphinx-theme and might not work with future versions of the theme.

[larsoner]

At least in MNE we get this page (from a toctree):

https://mne.tools/dev/python_reference.html

Clicking on "most used classes" goes to a page but the left sidebar is still there, and even going to "mne.io.Raw" still has the same setup:

https://mne.tools/dev/generated/mne.io.Raw.html#mne.io.Raw

@drammock did you have to do something special to get this behavior? Maybe the 'show_toc_level': 1 or the layout templates?

[rossbar]

I'm not sure, but it may be that that toctree from the master_doc is treated specially (e.g. to populate the navbar) and goes down a different code path than toctrees in other documents. Tweaking the available html_theme_options didn't seem to affect the rendered pages, but I'm sure I didn't try every configuration.

[rossbar]

xref: pydata/pydata-sphinx-theme#322

[drammock]

I didn't do anything special to get MNE-Python to work that way @larsoner . My understanding is that the toctree of the master doc determined the top-level navbar, and the left sidebar I think is determined by the toctrees of the first-level children of the master doc.

[rossbar]

My understanding is that the toctree of the master doc determined the top-level navbar, and the left sidebar I think is determined by the toctrees of the first-level children of the master doc.

That was my understanding as well - the reason why there is no (left) sidebar in numpydoc's case is that the first-level children don't have toctrees of their own.

[larsoner]

I also tried locally having a master_doc = 'contents.rst' and having the only stuff in contents.rst be a .. toctree:: that points to index, but this ends up making the top not very useful:

I'm fine with either solution you came up with @rossbar, which do you prefer?

[rossbar]

I prefer your solution @larsoner. Since it's not possible to get rid of/re-purpose the space of the left sidebar, I'd prefer the contents listing to be there rather than in the navbar. I like the way that my solution looks, but I don't like that it depends on undocumented features of the theme which feels too fragile to me. I don't feel strongly though, so I'm happy with whichever.

[larsoner]

I'll push mine and you can look at the rendered version. It makes the top useless, but something somewhere is useless in all of these, and I guess having it be the top will be the most consistent with other projects?

[jorisvandenbossche]

BTW, I personally think the navbar + sidebar is mostly useful for larger doc sites (like pandas), and so for smaller doc sites like numpydoc, I agree it's better to only use either the navbar or sidebar.

With the current solution you posted (#313 (comment)), you get a navbar that is not that useful. I think it should be possible to not make it "sticky", so it scrolls away (with some css).
Or alternatively to have no navbar at all. This is possible with the pydata-sphinx-theme with a bit of templating (see eg https://contextily.readthedocs.io/en/latest/), or otherwise you can also use the sphinx-book-theme, which is derived from the pydata-sphinx-theme and has no real navbar (https://sphinx-book-theme.readthedocs.io).

I like the way that my solution looks, but I don't like that it depends on undocumented features of the theme which feels too fragile to me.

Which undocumented features did it rely upon? Because looking at the commit you mentioned (0fd8506), this seems fine to me (overriding html_sidebars is documented).
(personally I think it might be better to keep the within-page TOC consistently on the right, so that aspect is consistent with eg the numpy docs, and so people might get more used to it).

[rossbar]

Which undocumented features did it rely upon?

Adding the :notoc: metadata to all of the .rst files. That prevents the docs-toc.html rendering in the right sidebar, but doesn't prevent it from being explicitly included on the left.

[larsoner]

I have a solution with html_sidebars = {"**": [],} that seems to be working well, will push momentarily...

[larsoner]

I'm happy with this, it's not perfect but no hacks required / it only uses standard config options:

https://276-11639513-gh.circle-artifacts.com/0/html/index.html

[larsoner]

(This is very similar to what you had @rossbar in 3db383a, apologies for the run-around on this!)

[rossbar]

Agreed this looks good - the only downside is that there's still the unused space on the left which becomes more pronounced e.g. when tiling the window to half the screen (the right sidebar, which contains useful info, disappears but the left is kept). That's a very minor thing though - I'm happy with this too (and big +1 for the doc title/ordering cleanups)

[larsoner]

Okay let's get this in and we can improve later if someone is motivated

[larsoner]

Thanks @rossbar !

[drammock]

FYI, I think (?) you could kill the left bar entirely by providing something like this for _templates/layout.html (caveat: not tested):

{%- extends "pydata_sphinx_theme/layout.html" %}
{% block docs_sidebar %}
{% endblock %}