Very poor navigation in new readthedocs builds

[ericsnekbytes]

Since the navigation and structure of new readthedocs builds is very poor, we should revert to the previous standard readthedocs theme (and move any in-progress work to a branch) until the issues noted below can be fixed:

[jtpio]

Since the navigation and structure of new readthedocs builds is very poor,

What does "new readthedocs builds" mean in this context?

The ReadTheDocs setup on the main branch has not changed for quite a while. It's using the same setup as most of the other projects with the pydata-sphinx-theme (like JupyterLab: https://jupyterlab.readthedocs.io/en/latest/).

[ericsnekbytes]

This page/link (stable) is the first result for "jupyterlab install" on google, which I believe uses sphinx-rtd-theme.

[ericsnekbytes]

It looks like many of the same issues are present there also, which makes me want to open a lab issue or combine them.

[ericsnekbytes]

The best way forward in both cases I think is to revert to the old theme (if this can be done with fairly minimal changes to the conf.py/related settings), develop changes in a new branch, then merge once navigation/structure issues are resolved. Edit: Reverting to sphinx-rtd-theme would be preferable so that this design does not end up in front of users (popular links are pointing to the classic theme), these are major readability/usability problems that are going to negatively impact docs users (and harm the jupyter experience/community).

[jtpio]

Edit: Reverting to sphinx-rtd-theme would be preferable so that this design does not end up in front of users (popular links are pointing to the classic theme), these are major readability/usability problems that are going to negatively impact docs users (and harm the jupyter experience/community).

Not sure this opinion is shared by everyone. The trend has been to adopt sphinx-pydata-theme over the past years, which has the nice benefit of giving a consistent look to the whole PyData ecosystem. It doesn't look like there have been a lot of complaints so far, does it?

Numpy uses it:

Pandas as well:

Probably a lot more in the PyData world.

and harm the jupyter experience/community

Not sure this holds true given that there is:

• https://jupyter-server.readthedocs.io/en/latest/
• https://jupyterhub.readthedocs.io/en/stable/
• https://jupyter-client.readthedocs.io/en/stable/index.html
• and many more...

revert to the old theme

Reverting the docs, and then switching again later will add unnecessary work to the already small crew of maintainers of the jupyter/notebook repo.

Instead wouldn't it be possible to suggest incremental improvements via pull requests? It looks like their documentation is very complete: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html

Also as an example the ipywidgets documentation has the left navigation bar displayed on the front page: https://ipywidgets.readthedocs.io/en/stable. Maybe this could be enabled on the notebook documentation as well? That could help address one of the points above.

[ericsnekbytes]

I can see that the theme change is global to the Jupyter org. I'll work on a focused PR to remedy some of the navigation issues. There's probably some rework that could be done around usage of the top and left bar and table-of-contents/summary pages that will help a lot. Edit: It seems like the numpy docs most successfully make use of the new theme, there are definitely some cues I can take from there.