Adopt pydata theme for the Iris Documentation

[tkknight]

ARCHIVED

was category = Ideas 💡

Original ...

We have made some good progress in getting to the point where the docs are easy to build, part of our CI, using standard tooling (Read The Docs) and is well presented. See the Live docs here: https://scitools-iris.readthedocs.io/en/latest/

However there seems to be a general move to using the pydata theme for Open Source projects (such as Cartopy!). I took the initiaitve and created a branch in my fork of Iris to play with the new theme and have successfully built it, see https://tkknight-iris-test-doc.readthedocs.io/en/latest/

The changes includes:

• Homepage is cleaner and uses icons to link to areas of the docs
• Icons in the top right for more resources
• Table of contents are on the left but the current views page contents are on the right.
• The docs render ok on a mobile device (try it!)
• I have noted some todo in the docs (summary on the main page), these are reminders for me to review/action more changes and will be removed if I progress this pr.

Before I iterate further I thought I would share this to garner feedback and to ensure it is something that is worth doing.

Comments welcome.

[bjlittle]

At SciPy2021 there seems to be some collective momentum towards "the crowd" adopting the pydata theme.

Personally, I think it's rather clean, and makes a bit better use of the real estate available.

Also, since cartopy has already moved to pydata, it would make sense from a SciTools branding perspective to also do so.

It's got my vote 👍

[trexfeathers]

At SciPy2021 there seems to be some collective momentum towards "the crowd" adopting the pydata theme.

Seconded!

This looks like an improvement to me. The API in particular feels easier to read (the RTD API format wins out aesthetically, but that's less important and they might be mutually exclusive). I also notice that the software version is omnipresent in the corner, which also solves #4031 and means one less job for #3935.

[tkknight]

A similar theme I have just found is https://sphinx-book-theme.readthedocs.io/en/latest/index.html. Used effectively by Pooch: https://www.fatiando.org/pooch/latest/.

Food for thought.

[trexfeathers]

I prefer the API rendering for this. Interactive elements sound cool too!

This discussion suggests it is less appropriate for rich, complex documentation, but I'd probably treat that as a cautionary note rather than iron guidance.

[tkknight]

The pydata theme has now been adopted, see #4661