Adopt sphinx design (#5127)

* index panel change wip

* syntax changes for panel and dropdown

* fixed extlinks warning

* minor tweaks

* indentations fixes and minor tweaks

* updated dependencies

* updated dependencies

* reinstated theme pin

* added todo

* removed todos

* fixed conflicts

* simplified dropdown use

* tidy up button options

* remove custom icons

* add whatsnew

* updated lockfiles

* min pin to sphinx

* unpin sphinx

* pin to sphinx 5.3

* sphinx pin test

Author: tkknight

docs/gallery_code/meteorology/plot_lagged_ensemble.py

@@ -5,16 +5,16 @@
 This example demonstrates the loading of a lagged ensemble dataset from the
 GloSea4 model, which is then used to produce two types of plot:
 
- * The first shows the "postage stamp" style image with an array of 14 images,
-   one for each ensemble member with a shared colorbar. (The missing image in
-   this example represents ensemble member number 6 which was a failed run)
-
- * The second plot shows the data limited to a region of interest, in this case
-   a region defined for forecasting ENSO (El Nino-Southern Oscillation), which,
-   for the purposes of this example, has had the ensemble mean subtracted from
-   each ensemble member to give an anomaly surface temperature. In practice a
-   better approach would be to take the climatological mean, calibrated to the
-   model, from each ensemble member.
+* The first shows the "postage stamp" style image with an array of 14 images,
+  one for each ensemble member with a shared colorbar. (The missing image in
+  this example represents ensemble member number 6 which was a failed run)
+
+* The second plot shows the data limited to a region of interest, in this case
+  a region defined for forecasting ENSO (El Nino-Southern Oscillation), which,
+  for the purposes of this example, has had the ensemble mean subtracted from
+  each ensemble member to give an anomaly surface temperature. In practice a
+  better approach would be to take the climatological mean, calibrated to the
+  model, from each ensemble member.
 
 """
 

docs/src/conf.py

@@ -157,7 +157,7 @@ def _dotv(version):
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx.ext.napoleon",
-    "sphinx_panels",
+    "sphinx_design",
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
@@ -167,9 +167,7 @@ def _dotv(version):
     autolog("Skipping the API docs generation (SKIP_API=1)")
 else:
     # better api documentation (custom)
-    extensions.extend(
-        ["custom_class_autodoc", "custom_data_autodoc", "generate_package_rst"]
-    )
+    extensions.extend(["custom_data_autodoc", "generate_package_rst"])
 
 # -- panels extension ---------------------------------------------------------
 # See https://sphinx-panels.readthedocs.io/en/latest/
@@ -239,11 +237,11 @@ def _dotv(version):
 # See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 
 extlinks = {
-    "issue": ("https://github.com/SciTools/iris/issues/%s", "Issue #"),
-    "pull": ("https://github.com/SciTools/iris/pull/%s", "PR #"),
+    "issue": ("https://github.com/SciTools/iris/issues/%s", "Issue #%s"),
+    "pull": ("https://github.com/SciTools/iris/pull/%s", "PR #%s"),
     "discussion": (
         "https://github.com/SciTools/iris/discussions/%s",
-        "Discussion #",
+        "Discussion #%s",
     ),
 }
 

docs/src/developers_guide/contributing_benchmarks.rst

@@ -38,8 +38,8 @@ applications.
 * Results for a series of commits can be visualised for an intuitive
   understanding of when and why changes occurred.
 
-    .. image:: asv_example_images/commits.png
-       :width: 300
+  .. image:: asv_example_images/commits.png
+     :width: 300
 
 * Parameterised benchmarks make it easy to visualise:
 

docs/src/further_topics/ugrid/operations.rst

@@ -53,7 +53,8 @@ structured formats and non-UGRID mesh formats.
 The objects created in this example will be used where possible in the
 subsequent example operations on this page.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -145,7 +146,8 @@ Creating a :class:`~iris.cube.Cube` is unchanged; the
 :class:`~iris.experimental.ugrid.Mesh` is linked via a
 :class:`~iris.experimental.ugrid.MeshCoord` (see :ref:`ugrid MeshCoords`):
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -206,7 +208,8 @@ The Iris saving process automatically detects if the :class:`~iris.cube.Cube`
 has an associated :class:`~iris.experimental.ugrid.Mesh` and automatically
 saves the file in a UGRID-conformant format:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -281,7 +284,8 @@ The :func:`iris.experimental.ugrid.save_mesh` function allows
 :class:`~iris.experimental.ugrid.Mesh`\es to be saved to file without
 associated :class:`~iris.cube.Cube`\s:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -352,7 +356,8 @@ loading a file remains **optional**. To load UGRID data from a file into the
 Iris mesh data model, use the
 :const:`iris.experimental.ugrid.PARSE_UGRID_ON_LOAD` context manager:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -372,7 +377,8 @@ All the existing loading functionality still operates on UGRID-compliant
 data - :class:`~iris.Constraint`\s, callbacks, :func:`~iris.load_cube`
 etcetera:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -415,7 +421,8 @@ The :func:`iris.experimental.ugrid.load_mesh` and
 :class:`~iris.experimental.ugrid.Mesh`\es to be loaded from a file without
 creating any associated :class:`~iris.cube.Cube`\s:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -469,7 +476,8 @@ be added to API in the near future.
 This first example uses GeoVista to plot the ``face_cube`` that we created
 earlier:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -539,7 +547,8 @@ earlier:
 
 Here's another example using a global cubed-sphere data set:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -614,7 +623,8 @@ therefore set to return an :class:`~iris.coords.AuxCoord` instead - breaking
 the link between :class:`~iris.cube.Cube` and
 :class:`~iris.experimental.ugrid.Mesh`:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. doctest:: ugrid_operations
 
@@ -657,7 +667,8 @@ mesh, we then reconstruct a :class:`~iris.experimental.ugrid.Mesh` from the
 ..
     Not using doctest here as want to keep GeoVista as optional dependency.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -784,7 +795,8 @@ with the
 ..
     Not using doctest here as want to keep iris-esmf-regrid as optional dependency.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -880,7 +892,8 @@ Since calling a regridder is usually a lot faster than initialising, reusing
 regridders can save a lot of time. We can demonstrate the reuse of the
 previously initialised regridder:
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 

docs/src/further_topics/ugrid/other_meshes.rst

@@ -27,7 +27,8 @@ To represent the Voronoi Polygons as faces, the corner coordinates will be used
 as the **nodes** when creating the Iris
 :class:`~iris.experimental.ugrid.mesh.Mesh`.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -115,7 +116,8 @@ as the **nodes** when creating the Iris
 :class:`~iris.experimental.ugrid.mesh.Mesh`.
 
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python
 
@@ -253,7 +255,8 @@ To make an unstructured cube, the data must be 'flattened' to convert the given
 dimensions into a single mesh dimension.  Since Iris cubes don't support a "reshape" or
 "flatten" operations, we create a new cube from the flattened data.
 
-.. dropdown:: :opticon:`code`
+.. dropdown:: :octicon:`code`
+    :color: light
 
     .. code-block:: python