Move the documentation to ReadTheDocs?

[greglucas]

It looks like Iris has moved their main documentation to ReadTheDocs: https://scitools-iris.readthedocs.io/en/stable/ Do we want to do that as well?

This would be much easier for a deploy hook on version release. It would also get us a version switcher for free, which would make my documentation overhaul PR a little easier to handle as well.

[tkknight]

The Iris devs made a focused effort to revitalise the documentation as the now legacy docs were not easy to build and it kinda felt unloved. I helped out with this. Other reasons:

• The legacy docs did not render well on small screen devices
• Navigation was not as easy as it should be
• We had too much customisation
• Way too many warnings when building using sphinx
• Lots of broken urls in the docs
• Lots of docstring formatting issues
• Was not easy to find out how to just install iris for use or to develop with (barrier to entry was high)
• No documentation on how to maintain the docs or how to contribute
• Release notes were inconsistent
• ....and more what I cannot recall atm 😄

All the above points were addressed, some by using more standard sphinx extensions and a fair bit of iteration - documentation is hard to write!

We found that using read the docs allowed us to:

• Automate docs build for each tagged release automatically
• Configure (via read the docs web portal) it to create docs for a branch if needed (can be hidden if in alpha). You can also create a new Read the docs instance based on a fork too.
• Version switcher (its all taken care of!)
• We adopted the latest (built against master) and stable (built against the most recent tagged version) naming convention

In terms of ensuring an element of QA the new docs built without any errors or warnings and now fail on read the docs if there is even a single warning, this forces any contributors to ensure links work, there are not syntax errors etc.

The documentation is far from perfect but we think it is a marked improvement from the v2.4 release.

If you want to check out how the build works, get Iris installed and then build it!

• https://scitools-iris.readthedocs.io/en/latest/installing.html#installing-from-source-with-conda-developers
• https://scitools-iris.readthedocs.io/en/latest/developers_guide/contributing_documentation.html#building

Alternatively see a recent CI job on cirrus-co https://cirrus-ci.com/build/5255294889492480, note the last 3 tasks are related to the documentation (click on any of them, then select the Run tests to see the outout.

I'll be happy to answer any questions on how we did this for Iris.

[greglucas]

Thanks @tkknight! My attempt at moving Cartopy to the pydata-sphinx theme (and removing all doc build errors) is in #1652.

One thing I'm not clear on is repo ownership and naming. i.e. Do we need someone from SciTools to create the RTD account and manage that side of things, and would we make the name scitools-cartopy.readthedocs or just cartopy.readthedocs?

[tkknight]

The RTD service let's you chose any name for the project. The project Iris was already taken by a different project, so using scitools-iris seemed to make sense. Also for any notable doc development I chose to create another project with the prefix of my github username and stating it is a test, see https://tkknight-iris-test-doc.readthedocs.io/en/latest/. This is configured to point to my fork and specific branch (I will disable this shortly, it is only needed for an active docs branch). Useful for others who are contributing/reviewing a PR to see the docs easily too without building.

If you do create one for cartopy (seems cartopy is already taken) you can also add maintainers (core devs) so others can configure and kick any builds if there are any issues.

Note you can also add a badge to an html page to show the status of the docs build, we include one on the Iris README.md.

[QuLogic]

It seems like someone did setup cartopy on RTD; maybe @pelson?

[greglucas]

Do we want to discuss moving the docs again? We just released to the scitools.org.uk repository, but it would be nice to remove that manual step and automatically upload them somewhere else. Another option would be GitHub Pages, which I didn't realize was already set up and has some content in it... https://scitools.github.io/cartopy/ But, I can't see the gh-pages or any other branch that would be serving that content... Maybe it is protected and only admins can view that branch?

[pelson]

But, I can't see the gh-pages or any other branch that would be serving that content... Maybe it is protected and only admins can view that branch?

:thinking: - I don't know how this is working. Strange indeed.

I have added Greg and Ryan as maintainers on the readthedocs cartopy instance (couldn't find your handle Elliott). When I prototyped that way-back-when, we had significant problems with building cartopy on the RTD infra, but I understand that the landscape has changed a lot since then.

[dopplershift]

Pretty sure it's getting deployed from the cartopy/ directory from the main org docs repo. The cartopy repo itself isn't set up for gh-pages. Not sure what would happen if we did set it up, my guess is that it would override the org page.

Personally, at this point I lean just using plain GH pages, just because that's what I know these days. The pydata-sphinx-theme (if we went that way) has a built-in version picker nowadays.

[rcomer]

RTD search seems broken: https://github.com/SciTools/iris/issues/5383