Adopt sphinx-apidoc and retire complex sphinxext (SciTools#5264)

* baseline.

* updated whatsnew

* updated conda yml and lock files

* lockfile update

* lockfiles updated

* Update docs/src/whatsnew/latest.rst

Co-authored-by: Patrick Peglar <[email protected]>

---------

Co-authored-by: Patrick Peglar <[email protected]>

Author: tkknight

docs/src/common_links.inc

@@ -35,6 +35,7 @@
 .. _SciTools: https://github.com/SciTools
 .. _scitools-iris: https://pypi.org/project/scitools-iris/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
+.. _sphinx-apidoc: https://github.com/sphinx-contrib/apidoc
 .. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash
 .. _using git: https://docs.github.com/en/github/using-git
 .. _requirements: https://github.com/SciTools/iris/tree/main/requirements

docs/src/conf.py

@@ -143,7 +143,7 @@ def _dotv(version):
 """
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
     "sphinx.ext.todo",
@@ -166,8 +166,8 @@ def _dotv(version):
 if skip_api == "1":
     autolog("Skipping the API docs generation (SKIP_API=1)")
 else:
-    # better api documentation (custom)
-    extensions.extend(["custom_data_autodoc", "generate_package_rst"])
+    extensions.extend(["sphinxcontrib.apidoc"])
+    extensions.extend(["api_rst_formatting"])
 
 # -- Napoleon extension -------------------------------------------------------
 # See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
@@ -198,13 +198,36 @@ def _dotv(version):
 # api generation configuration
 autodoc_member_order = "groupwise"
 autodoc_default_flags = ["show-inheritance"]
+
+# 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 = "init"
+autoclass_content = "both"
 modindex_common_prefix = ["iris"]
 
+# -- 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 = []
+
+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}")
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -381,13 +404,8 @@ def _dotv(version):
 }
 
 # -----------------------------------------------------------------------------
-# Remove matplotlib agg warnings from generated doc when using plt.show
-warnings.filterwarnings(
-    "ignore",
-    category=UserWarning,
-    message="Matplotlib is currently using agg, which is a"
-    " non-GUI backend, so cannot show the figure.",
-)
+# Remove warnings
+warnings.filterwarnings("ignore")
 
 # -- numfig options (built-in) ------------------------------------------------
 # Enable numfig.

docs/src/developers_guide/contributing_documentation_full.rst

@@ -43,16 +43,16 @@ achieved via::
 
     make html-noplot
 
-Another option is to skip the :ref:`iris` documentation creation.  This can be
+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::
 
     make html-noapi
 
 You can combine both the above and skip the
-:ref:`contributing.documentation.gallery` and :ref:`iris` documentation
-completely.  This can be achieved via::
+:ref:`contributing.documentation.gallery` and :doc:`../generated/api/iris`
+documentation completely.  This can be achieved via::
 
     make html-quick
 

docs/src/developers_guide/documenting/docstrings.rst

@@ -6,7 +6,8 @@ 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 :ref:`Iris`.
+the code and may be read directly in the source or via the
+:doc:`../../generated/api/iris`.
 
 .. note::
    As of April 2022 we are looking to adopt `numpydoc`_ strings as standard.

docs/src/index.rst

@@ -191,7 +191,7 @@ The legacy support resources:
    :maxdepth: 1
    :hidden:
 
-   generated/api/iris
+   Iris API <generated/api/iris>
 
 
 .. toctree::

docs/src/sphinxext/api_rst_formatting.py

@@ -0,0 +1,36 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+
+# This script will process all .rst files that have been created by
+# sphinxcontrib.apidoc extension and perform minor changes, specifically:
+#
+# - Remove the suffix for "package" and " module".
+#
+
+import ntpath
+from pathlib import Path
+
+
+def main_api_rst_formatting(app):
+    src_dir = Path("generated/api")
+
+    print(f"[{ntpath.basename(__file__)}] Processing RST files", end="")
+
+    for file in src_dir.iterdir():
+        print(f".", end="")
+
+        with open(file, "r") as f:
+            lines = f.read()
+
+        lines = lines.replace(" package\n=", "\n")
+        lines = lines.replace(" module\n=", "\n")
+
+        with open(file, "w") as f:
+            f.write(lines)
+    print("")
+
+def setup(app):
+    app.connect("builder-inited", main_api_rst_formatting)