Changes theme to pydata-sphinx-theme

[billbrod]

Describe the change in this PR at a high-level

This PR changes our sphinx theme to pydata-sphinx-theme. It also reorganizes the documentation inline with the suggestions from the pyOpenSci review.

NOTE: Failing url is expected and won't change in this PR. For pydata theme's version switcher, we need to point to a json that lives at a persistent url (i.e., not within the docs folder) so that the version switcher can get updated with new versions as they get released without rebuilding old documentation. I have put a first draft of that json in this PR, but the url that version switcher points to won't work until after this PR is merged (because it's pointing to the built docs from the main branch). I'm now realizing I could include the json but not configure the switcher in this PR (since I haven't added the switcher to the theme anyway) -- what do you think?

Link any related issues, discussions, PRs

Closes #360, #21.

Related open issues, will address these later:

• finish version switcher, fix jenkins build on release Jenkins not building documentation on github release #399
• fix binder (broken because of switch to myst-nb) Fix binder #409
• update image on index page (I think it's too cryptic) Update images on index page #406
• update installation instructions to discuss uv Update installation instructions #400.

Also, the names of some of the API pages are really long. As part of #246 , I will be changing how things are named and fix this.

Outstanding questions / particular feedback

• Big picture, how does this look?
• Most of the content has not changed, with the following exceptions:
  • main index has been reworked, adding buttons and removing unnecessary text
  • contributing info moved from CONTRIBUTING.md in main repo to docs/developers/contributing.md
  • new index pages because of the restructure (see below)
• Switching to this theme involves changing the structure of the docs to use many more subfolders with toctrees. This has led to the creation of many more index pages (e.g., getting_started/index). I'm not really sure what to put there -- how do they look? For "Getting Started", "User Guide", "Reference", and "For developers", I put a brief summary of the contents of that section. For the more nested ones (all the sections within "Getting Started"), I just had them show the full toctree.
• Relatedly, for the PortillaSimoncelli docs, I ideally would not have an index page for each section (e.g., "Portilla-Simoncelli / Getting started"). But I couldn't figure out a way to remove that and still have the nice nesting in the sidebar. So those index pages just contain the full toctrees. How does that look?
• For the API section, things are slightly complicated because I'm not having each function / class on its own page, but using module-level pages. These are generated in the (hidden) docs/api_modules.rst page. In order to make it so you can use the next/previous buttons at the bottom to navigate between them, I had to add a single hidden toctree in api.rst which includes all of the pages.
  • I could have instead just had this hidden toctree include api_modules.rst, but then that page (which I don't want people to look at) gets included in the hierarchy and looks weird. And I can't just include the contents of api_modules.rst in api.rst because there's no way to hide a autosummary like a toctree.
  • I'm fine with how the current setup looks, but am worried about forgetting to add something to that hidden toctree, which doesn't raise a warning / error from sphinx's point of view. I could add one of my little linter scripts in linting/, but is there something else I'm missing?
• In the API docs, I would've liked to configure the secondary sidebar table of contents to have different depths per-page and to just use the method name instead of object.method (e.g., load instead of Metamer.load), but I couldn't figure out how to do that with the theme.

Describe changes

• Changed theme to pydata-sphinx
• Reorganize documentation, moving things into different sub-categories, with index pages and toctrees as needed for new theme.
• Adds a bit of text to the highest level of these index pages (see above).
• Makes images / logos handle dark mode / light mode better
• Adds version_switcher json file, though the version switcher itself is not currently activated. will add in subsequent PR (see Jenkins not building documentation on github release #399)
• Add ability to move previous and next in API docs
• Moves CONTRIBUTING.md contents into docs, replaces that with something brief with a link.
• Changes a handful of links from path-dependent to using the sphinx explicit anchors

Checklist

Affirm that you have done the following:

• I have described the changes in this PR, following the template above.
• I have added any necessary tests.
• I have added any necessary documentation. This includes docstrings, updates to existing files found in docs/, or (for large changes) adding new files to the docs/ folder.
• If a public new class or function was added: I have double-checked that it is present in the API docs, modifying docs/api.rst and docs/api_modules.rst to include it if necessary.

[billbrod]

Documentation built by flatiron-jenkins at http://docs.plenoptic.org/docs//pulls/410

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.