Merge da570a8 into 5c18504

Author: tkknight

.pre-commit-config.yaml

@@ -76,3 +76,11 @@ repos:
       - id: numpydoc-validation
         exclude: "^lib/iris/tests/|docs/gallery_code/"
         types: [file, python]
+
+-   repo: local
+    hooks:
+    -   id: check-attribute-comment
+        name: use triple quote docstring proceding attribute
+        types: [python]
+        entry: '#:'
+        language: pygrep

benchmarks/benchmarks/generate_data/__init__.py

@@ -26,11 +26,12 @@
 from iris._lazy_data import as_concrete_data
 from iris.fileformats import netcdf
 
-#: Python executable used by :func:`run_function_elsewhere`, set via env
-#:  variable of same name. Must be path of Python within an environment that
-#:  includes Iris (including dependencies and test modules) and Mule.
 try:
     DATA_GEN_PYTHON = environ["DATA_GEN_PYTHON"]
+    """Python executable used by :func:`run_function_elsewhere`, set via env variable of same name.
+       Must be path of Python within an environment that
+       includes Iris (including dependencies and test modules) and Mule."""
+
     _ = check_output([DATA_GEN_PYTHON, "-c", "a = True"])
 except KeyError:
     error = "Env variable DATA_GEN_PYTHON not defined."

docs/src/conf.py

@@ -22,7 +22,6 @@
 import datetime
 from importlib.metadata import version as get_version
 from inspect import getsource
-import ntpath
 import os
 from pathlib import Path
 import re
@@ -32,10 +31,32 @@
 from urllib.parse import quote
 import warnings
 
+from sphinx.util import logging
+from sphinx.util.console import colorize
 
-# function to write  useful output to stdout, prefixing the source.
-def autolog(message):
-    print("[{}] {}".format(ntpath.basename(__file__), message))
+
+def autolog(message: str, section: str | None = None, color: str | None = None) -> None:
+    """Log the diagnostics `message` with optional `section` prefix.
+
+    Parameters
+    ----------
+    message : str
+        The diagnostics message.
+    section : str, optional
+        The prefix text for the diagnostics message.
+    color : str, optional
+        The color of the `section` prefix text.
+
+    """
+    if color is None:
+        color = "brown"
+
+    section = colorize(color, colorize("bold", f"[{section}] ")) if section else ""
+    msg = f'{colorize(color, section)}{colorize("darkblue", f"{message}")}'
+    logger.info(msg)
+
+
+logger = logging.getLogger("sphinx-iris")
 
 
 # -- Check for dev make options to build quicker
@@ -63,17 +84,20 @@ def autolog(message):
 # rtd_version = "my_branch"   # useful for testing
 
 if on_rtd:
-    autolog("Build running on READTHEDOCS server")
+    autolog("Build running on READTHEDOCS server", section="ReadTheDocs")
 
     # list all the READTHEDOCS environment variables that may be of use
-    autolog("Listing all environment variables on the READTHEDOCS server...")
+    autolog(
+        "Listing all environment variables on the READTHEDOCS server...",
+        section="ReadTheDocs",
+    )
 
     for item, value in os.environ.items():
-        autolog("[READTHEDOCS] {} = {}".format(item, value))
+        autolog("{} = {}".format(item, value), section="ReadTheDocs")
 
 # -- Path setup --------------------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
+# If extensions (or modules to document with api) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
@@ -101,8 +125,8 @@ def autolog(message):
 # |version|, also used in various other places throughout the built documents.
 version = get_version("scitools-iris")
 release = version
-autolog(f"Iris Version = {version}")
-autolog(f"Iris Release = {release}")
+autolog(f"Iris Version = {version}", section="General", color="blue")
+autolog(f"Iris Release = {release}", section="General", color="blue")
 
 # -- General configuration ---------------------------------------------------
 
@@ -148,14 +172,13 @@ def _dotv(version):
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
+    "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.duration",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
-    "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx.ext.napoleon",
@@ -166,10 +189,10 @@ def _dotv(version):
 ]
 
 if skip_api == "1":
-    autolog("Skipping the API docs generation (SKIP_API=1)")
+    autolog("Skipping the API docs generation (SKIP_API=1)", section="General")
 else:
-    extensions.extend(["sphinxcontrib.apidoc"])
-    extensions.extend(["api_rst_formatting"])
+    # build will break if this is not one of the first extensions loaded.
+    extensions.insert(0, "autoapi.extension")
 
 # -- Napoleon extension -------------------------------------------------------
 # See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
@@ -195,49 +218,57 @@ def _dotv(version):
 
 # sphinx.ext.todo configuration -----------------------------------------------
 # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
-todo_include_todos = False
-todo_emit_warnings = False
+todo_include_todos = True
 
-# sphinx.ext.autodoc configuration --------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
-autodoc_default_options = {
-    "members": True,
-    "member-order": "alphabetical",
-    "undoc-members": True,
-    "private-members": False,
-    "special-members": False,
-    "inherited-members": True,
-    "show-inheritance": True,
-}
+# -- autodoc options ---------------------------------------------------------
+# See https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-include-type-annotations-as-types-in-rendered-docstrings
+#     https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
 
-# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints
-autodoc_typehints = "none"
-autosummary_generate = True
-autosummary_imported_members = True
-autopackage_name = ["iris"]
-autoclass_content = "both"
-modindex_common_prefix = ["iris"]
+# -- autoapi extensions -------------------------------------------------------
+# See https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
+#     https://github.com/readthedocs/sphinx-autoapi
+todo_include_todos = False
+todo_emit_warnings = False
 
 # -- apidoc extension ---------------------------------------------------------
 # See https://github.com/sphinx-contrib/apidoc
-source_code_root = (Path(__file__).parents[2]).absolute()
-module_dir = source_code_root / "lib"
-apidoc_module_dir = str(module_dir)
-apidoc_output_dir = str(Path(__file__).parent / "generated/api")
-apidoc_toc_file = False
-
-apidoc_excluded_paths = [
-    str(module_dir / "iris/tests"),
-    str(module_dir / "iris/experimental/raster.*"),  # gdal conflicts
-]
 
-apidoc_module_first = True
-apidoc_separate_modules = True
-apidoc_extra_args = []
+if skip_api != "1":
+    source_code_root = (Path(__file__).parents[2]).absolute()
+    module_dir = source_code_root / "lib"
+
+    autoapi_dirs = [module_dir]
+    autoapi_root = "generated/api"
+    autoapi_ignore = [
+        str(module_dir / "iris/tests/*"),
+        str(module_dir / "iris/experimental/raster.*"),  # gdal conflicts
+    ]
+    autoapi_member_order = "alphabetical"
+    autoapi_options = [
+        "members",
+        "inherited-members",
+        "undoc-members",
+        # 'private-members',
+        # "special-members",
+        "show-inheritance",
+        # "show-inheritance-diagram",
+        "show-module-summary",
+        "imported-members",
+    ]
+
+    autoapi_python_class_content = "both"
+    autoapi_keep_files = True
+    autoapi_add_toctree_entry = False
+
+    # https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#suppressing-warnings
+    suppress_warnings = ["autoapi.python_import_resolution"]
 
-autolog(f"[sphinx-apidoc] source_code_root = {source_code_root}")
-autolog(f"[sphinx-apidoc] apidoc_excluded_paths = {apidoc_excluded_paths}")
-autolog(f"[sphinx-apidoc] apidoc_output_dir = {apidoc_output_dir}")
+    autolog(f"[autoapi] source_code_root = {source_code_root}", section="AutoAPI")
+    autolog(f"[autoapi] autoapi_dirs     = {autoapi_dirs}", section="AutoAPI")
+    autolog(f"[autoapi] autoapi_ignore   = {autoapi_ignore}", section="AutoAPI")
+    autolog(f"[autoapi] autoapi_root     = {autoapi_root}", section="AutoAPI")
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -307,7 +338,7 @@ def _dotv(version):
     "footer_end": ["custom_footer"],
     "navigation_depth": 3,
     "navigation_with_keys": False,
-    "show_toc_level": 2,
+    "show_toc_level": 3,
     "show_prev_next": True,
     "navbar_align": "content",
     # removes the search box from the top bar

docs/src/developers_guide/contributing_documentation_full.rst

@@ -43,16 +43,17 @@ achieved via::
 
     make html-noplot
 
-Another option is to skip the :doc:`../generated/api/iris` documentation creation.  This can be
-useful as it reduces the time to build the documentation, however you may have
-some build warnings as there maybe references to the API documentation.
-This can be achieved via::
+Another option is to skip the :doc:`Iris API </generated/api/iris/index>` documentation
+creation.  This can be useful as it reduces the time to build the documentation,
+however you may have some build warnings as there maybe references to the API
+documentation.  This can be achieved via::
 
     make html-noapi
 
 You can combine both the above and skip the
-:ref:`contributing.documentation.gallery` and :doc:`../generated/api/iris`
-documentation completely.  This can be achieved via::
+:ref:`contributing.documentation.gallery` and
+:doc:`Iris API </generated/api/iris/index>` documentation completely.  This can
+be achieved via::
 
     make html-quick
 

docs/src/developers_guide/contributing_getting_involved.rst

@@ -59,7 +59,7 @@ If you are new to using GitHub we recommend reading the
    :caption: Reference
    :hidden:
 
-   ../generated/api/iris
+   Iris API <../generated/api/iris/index>
    ../whatsnew/index
    ../copyright
    ../voted_issues

docs/src/developers_guide/documenting/docstrings.rst

@@ -1,3 +1,4 @@
+.. include:: ../../common_links.inc
 .. _docstrings:
 
 ==========
@@ -7,7 +8,7 @@ Docstrings
 Every public object in the Iris package should have an appropriate docstring.
 This is important as the docstrings are used by developers to understand
 the code and may be read directly in the source or via the
-:doc:`../../generated/api/iris`.
+:doc:`Iris API </generated/api/iris/index>`.
 
 .. note::
    As of April 2022 we are looking to adopt `numpydoc`_ strings as standard.

docs/src/index.rst

@@ -82,7 +82,7 @@ For more information see :ref:`why_iris`.
         Browse full Iris functionality by module.
 
         +++
-        .. button-ref:: generated/api/iris
+        .. button-ref:: generated/api/iris/index
             :ref-type: doc
             :color: primary
             :outline:
@@ -200,7 +200,7 @@ The legacy support resources:
    :maxdepth: 1
    :hidden:
 
-   Iris API <generated/api/iris>
+   Iris API <generated/api/iris/index>
 
 
 .. todolist::

docs/src/sphinxext/api_rst_formatting.py

@@ -243,16 +243,14 @@ def context(self, **kwargs):
             self.__dict__.update(current_state)
 
 
-#: Object containing all the Iris run-time options.
 FUTURE = Future()
+"""Object containing all the Iris run-time options."""
 
-
-# Initialise the site configuration dictionary.
-#: Iris site configuration dictionary.
 site_configuration: dict[
     Literal["cf_profile", "cf_patch", "cf_patch_conventions"],
     Callable | Literal[False] | None,
 ] = {}
+"""Initialise the site configuration dictionary."""
 
 try:
     from iris.site_config import update as _update