Use pytest to run doctests -- or a runner #6110

📰 Custom Issue

How to run doctests - pytest documentation

We currently rely on our docs rendering to run our doctests. This introduces many problems:

1. Unnecessarily long run time - must first build the docs before running the doctests.
2. Confusingly wide CI scope - the CI doctest session must first build the docs. We regularly get doctest 'failures' that are actually docs build failures, and this has been known to confuse developers.
3. Difficult to run individual doctests - must use a specific series of arguments with a docs build command. This took me 4 years to figure out! sphinx-build -b doctest -d _build/doctrees . _build/doctest generated/api/iris.util.rst.
4. @tkknight and @bjlittle are discovering that the number of doctests that actually get run is had to understand. It seems to depend on how the docs are built, and is difficult to debug specifically because it is hidden behind a docs builder. DOCS: Adopt sphinx-autoapi #6102

pytest is a mature, purpose-built tool. It can directly run doctests from .rst files (points 1 and 2), its syntax is familiar and aimed at being easy (point 3), and its terminal output is also the subject of much refinement (point 4). I believe the only reason we're not already using it for doctests is that it didn't occur to us when we adopted pytest as the runner for our 'normal' tests.

Proposed to-do

• Complete https://github.com/pp-mo/ncdata/pull/177
• Create a template from the ncdata solution
• Apply the template to Iris
• Refactor template based on Iris