DOC: Update sphinx, numpydoc, and pydata-sphinx-theme

[jarrodmillman]

Updates for sphinx, numpydoc, and pydata-sphinx-theme.

The new version of the pydata-sphinx-theme adds a theme switcher (light, dark, auto mode) among other improvements. I've set it to default to light mode for now. Once we have more feedback on the dark theme, we can set it to auto mode.

[mattip]

There are documentation build warnings (that make the build fail). Did something chagne in the autodoc summaries?

WARNING: unsupported theme option 'logo_link' given
/home/circleci/repo/doc/source/reference/arrays.interface.rst:249: WARNING: unknown document: c-api/buffer
/home/circleci/repo/venv/lib/python3.8/site-packages/numpy/__init__.py:docstring of numpy.arange:88: WARNING: unknown document: c-api/long
docstring of numpy.ma.arange:88: WARNING: unknown document: c-api/long
/home/circleci/repo/doc/source/user/basics.interoperability.rst:46: WARNING: unknown document: c-api/buffer
/home/circleci/repo/doc/source/user/how-to-how-to.rst:108: WARNING: unknown document: content/tutorial-style-guide
/home/circleci/repo/doc/source/user/quickstart.rst:1488: WARNING: unknown document: content/tutorial-svd
make: *** [Makefile:183: html-build] Error 1

Exited with code exit status 2

[rgommers]

Thanks @jarrodmillman. The theme and numpydoc upgrades look good to me.

For the Sphinx upgrade: 5.0.1 is super recent, that's going to be annoying for contributors to deal with. We have always tried to maintain support for a reasonably old Sphinx version (e.g. as packaged in most common Linux distros; latest Ubuntu is at 4.3.2). Is there a need to upgrade so aggressively?

[jarrodmillman]

There is some follow-up work that needs to be done to make the website look better with the dark mode.Before doing that I wanted to check that everything else looks OK to folks. (For example, the logo text is black and doesn't show up well with the dark theme. So we will want to make a logo for the dark theme as well as the light theme.)

@rgommers Does setting the minimum sphinx version to 4.3 (released Nov 2021) make sense? We could go with 4.2 (released Sept. 2021) if 4.3 is too recent.

(If would prefer having 4.2 or more recent, since sphinx < 4.2 doesn't work under python 3.10 or above. If we do want to support sphinx < 4.2, we should put in some logic to make sure it doesn't try to use sphinx < 4.2 when the Python version is greater than 3.10.)

[rgommers]

Sphinx 4.3 sounds fine to me, thanks Jarrod.

So we will want to make a logo for the dark theme as well as the light theme

We don't have one I think, but that shouldn't be hard to do. Do you think just making the logo text white is better, or make an all-white version of the logo?

[charris]

Lets get this in and leave fixing the logo for the dark theme for another PR.

[charris]

Thanks Jarrod.

[melissawm]

We do have this one: https://github.com/numpy/numpy/blob/main/branding/logo/primary/numpylogolight.png

Could be a starting point?