Use pydata theme

[tkknight]

🚀 Pull Request

Description

WORKING IN PROGRESS - DO NOT MERGE

Adoption of the pydata theme (https://pydata-sphinx-theme.readthedocs.io/en/latest/) for Iris. This has meant some slight restructuring of the rst files to allow for the navigation.

Others changes of note:

• Add icons to each section on homepage
• Added a icon and link to the support (Iris Discussions)
• Added the version number as text after the logo in the top left corner. It also shows "latest" or "stable" if appropriate.

I plan to bring the PR out of draft after Iris 3.2 has been released.

You can view the built docs here: https://tkknight-iris-test-doc.readthedocs.io/en/latest/

Related to #4344

TODO

• Decide how to handle the figure labelling in the gallery, imho the figure numbering spacing is too close. Experimenting in theme_override.css. Was tempted to disable the figure numbering, not there yet though.
• Post messages on legacy support channels driving traffic to Github discussions instead (after this PR is merged/released?)
• Remove the TODOs in the source (auto populates todo entries on the index page for easy reference)
• Whats new
• Considers structuring docs around the quadrants tutorials, how- to's, explanation, reference (see https://documentation.divio.com/). This could be a follow on pr.
• Could incoporate the Getting Started into the user guide.

---

Consult Iris pull request check list

[pp-mo]

Some random comments on this ...

Most broadly, I love the layout + structure but dislike the rendering.

On the plus side, I really like the layout, epecially the way that the sections now run across the top as main headings/tabs.

On the minus side, I find the extreme paleness of everything with the thin fonts really hard on the eyes, and lacking in highlighting for different types of content

• external links are hard to spot because the blue is so muted
• internal links (the Sphinx ones) are also too discreet, and are no longer visually distinguished from the external ones
  • (existing internal links have a clear box outline)
• code boxes don't stand out very strongly : existing docs have a strong pale green background for this
• everything runs together, the only thing breaking the flow is the headings (though these are fairly bold)

On the other hand, I guess there is nothing that we can do about that if we want to be consistent with Numpy docs et al?
But I did agree with @trexfeathers that sphinx-book is generally easier to look at - and, I think, to navigate

Some detail points

• In the API pages, I miss the clear highlighting of class headers (existing ones have a light-blue background)
• In the User Guide, we don't seem to have subsections appearing in the LHS index (though we do still have a multi-level index for the API pages)

[pp-mo]

P.S. however, looking at the Pandas and Bokeh docs, it looks like those visibility points can be addressed while staying within the "pydata theme".
numpy maybe not so much -- that one does seem to suffer from the same criticisms (for me)

[rcomer]

Is it possible to put a gallery link somewhere more prominent? Both Matplotlib and Cartopy have the Examples/Gallery link in the top bar, so if we did the same I think it would be more intuitive for users to find.

[tkknight]

Surpassed by #4661