tkknight

[PI] Docs: Potential Future Improvements Overview

2

## 📚 Documentation The Iris docs have been **overhauled** ready for the **Iris 3.0.0** release but I have some ideas on how to improve more.... ### Small things - [...

Iris Documentation: Needs to be dark mode friendly

3

## 📚 Documentation `pydata-sphinx-theme` has been updated from `0.8.1` to `0.9.0`. The later version supports dark mode which is great, however the iris docs will need a few changes like...

Discussion: Use of google groups for support for users/devs.

13

## 📰 Custom Issue On our Iris [documentation ](https://scitools-iris.readthedocs.io/en/latest/) there is a **SUPPORT** section in the **sidebar** with links to: - [Users Google Group](https://groups.google.com/forum/#!forum/scitools-iris) - **14** topics posted so far...

numpdoc adoption tick list

2

## 📚 Documentation Below is a list of all the python files in ``iris/lib``. In order to make ground ensuring our code based support numpdoc fully the below checklist can...

DOCS: Enable numpydoc validation pre-commit hook

2

## 🚀 Pull Request ### Description This pull-request enables the `numpydoc` pre-commit hook, which performs [validation checks](https://numpydoc.readthedocs.io/en/latest/validation.html) of all python docstrings to ensure that they comply with the [numpydoc validation...

## 📚 Documentation The pre-commit hook to check these rules was added in https://github.com/SciTools/iris/pull/5762. The outstanding rules review and ideally adoption are below as defined in [pyproject.toml](https://github.com/SciTools/iris/blob/main/pyproject.toml ) (section `[tool.numpydoc_validation]`)....

DOCS: Adopt autoapi v3 for our API doc generation.

5

## 📚 Documentation We currently use [apidoc](https://github.com/sphinx-contrib/apidoc) for our API Docs, which look like this: https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html. Autodoc headline: > Sphinx AutoAPI is a Sphinx extension for generating complete API documentation...

DOCS: replace napolean with numpydoc for the API docs.

4

## 🚀 Pull Request # WIP. DO NOT REVIEW OR MERGE ### Description Retires [napolean ](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)in favour of [numpydoc](https://numpydoc.readthedocs.io/en/latest/validation.html). This is more compatible with the numpy docstrings we now use....

DOCS: Adopt sphinx-autoapi

18

## 🚀 Pull Request # `DRAFT - NOT TO BE REVIEWED YET` ### Description Adoption of `sphinx-autoapi` over the default of autodoc. Solves https://github.com/SciTools/iris/issues/5708. - Added `sphinx-autoapi` (>=3.0.0) - Improves...