Swap to pydata-sphinx-theme

[davidorme]

Description

This is a draft PR with a demo of using the pydata-sphinx-theme instead of the rtd-sphinx-theme.

The docs under this PR are built here:

https://virtual-ecosystem.readthedocs.io/en/1219-pydata-theme-version/

Apart from swapping out the theme in the configuration, the main changes are to the table of contents listing (_toc.yaml) to group the docs under a small number of main headings. I've also added a few stub pages to get the TOC to build - these might well be replaced by existing overview.

The theme has:

• the top level headings (Implementation, Users, Developers, API, Reference) along the top.
• the section navigation within one of those top level headings appears on the left when you enter a section
• the page table of contents appears on the right within a page.

I think this is hugely better than what we currently have - the theme is well supported, has a bunch of interesting other features and a really clean style.

Fixes #1219

Type of change

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist

• Make sure you've run the pre-commit checks: $ pre-commit run -a
• All tests pass: $ poetry run pytest

Further checks

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works
• Relevant documentation reviewed and updated

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.02%. Comparing base (0f4f9ed) to head (d470c38).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1236      +/-   ##
===========================================
- Coverage    95.03%   95.02%   -0.02%     
===========================================
  Files           71       71              
  Lines         7278     7278              
===========================================
- Hits          6917     6916       -1     
- Misses         361      362       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[jacobcook1995]

At first glance it looks like a significant improvement! (showing the entire TOC tree to all visitors meant that we were giving users a huge amount of hard to parse information). So think this is a good change

[davidorme]

There's still a lot of work to do in deciding which pages go where (variables is hidden) and what is the landing page for each top "tab" but the structure is so much clearer.

[sallymatson]

Some UI issues I've noticed - mainly using dark mode. For any of these we can't get to before merging, we can make into a UI milestone or meta issue to keep track of?

• Some table colouring issues in dark model - see for e.g. abiotic_simple_implementation.html
• I strongly prefer the layout of the top bar as it is in the Pandas documentation, where it's left aligned instead of slightly off-center.
• This spacing in the right sidebar is a bit jarring and adds too much noise. Could we delete the This Page section?

• Issues with color backed things e.g. see boxes on core_configuration.html and the photos on the project team page