Iris Docs: Dark theme ready (#5299)

* baseline

* remove comments

* reinstated

* added whatsnew

* review changes

docs/src/_static/theme_override.css

@@ -1,5 +1,5 @@
 /* import the standard theme css */
-@import url("css/theme.css"); 
+@import url("styles/theme.css");
 
 /* now we can add custom css.... */
 

docs/src/conf.py

@@ -317,9 +317,9 @@ def _dotv(version):
     ],
     "use_edit_page_button": True,
     "show_toc_level": 1,
-    # Omitted `theme-switcher` below to disable it
+    # Omit `theme-switcher` from navbar_end below to disable it
     # Info: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode
-    "navbar_end": ["navbar-icon-links"],
+    # "navbar_end": ["navbar-icon-links"],
     # https://pydata-sphinx-theme.readthedocs.io/en/v0.11.0/user_guide/branding.html#different-logos-for-light-and-dark-mode
     "logo": {
         "image_light": "_static/iris-logo-title.svg",
@@ -338,7 +338,7 @@ def _dotv(version):
     "doc_path": "docs/src",
     # default theme.  Also disabled the button in the html_theme_options.
     # Info: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode
-    "default_mode": "light",
+    "default_mode": "auto",
     # custom
     "on_rtd": on_rtd,
     "rtd_version": rtd_version,
@@ -355,13 +355,14 @@ def _dotv(version):
 html_static_path = ["_static"]
 html_style = "theme_override.css"
 
-# this allows for using datatables: https://datatables.net/
+# this allows for using datatables: https://datatables.net/.
+# the version can be manually upgraded by changing the urls below.
 html_css_files = [
-    "https://cdn.datatables.net/1.10.23/css/jquery.dataTables.min.css",
+    "https://cdn.datatables.net/1.13.4/css/jquery.dataTables.min.css",
 ]
 
 html_js_files = [
-    "https://cdn.datatables.net/1.10.23/js/jquery.dataTables.min.js",
+    "https://cdn.datatables.net/1.13.4/js/jquery.dataTables.min.js",
 ]
 
 # url link checker.  Some links work but report as broken, lets ignore them.

docs/src/further_topics/ugrid/operations.rst

@@ -53,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -146,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -208,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -284,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -356,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -377,8 +377,8 @@ All the existing loading functionality still operates on UGRID-compliant
 data - :class:`~iris.Constraint`\s, callbacks, :func:`~iris.load_cube`
 etcetera:
 
-.. dropdown:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -421,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -476,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. code-block:: python
 
@@ -547,8 +547,8 @@ earlier:
 
 Here's another example using a global cubed-sphere data set:
 
-.. dropdown:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. code-block:: python
 
@@ -623,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. doctest:: ugrid_operations
 
@@ -667,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. code-block:: python
 
@@ -795,8 +795,8 @@ with the
 ..
     Not using doctest here as want to keep iris-esmf-regrid as optional dependency.
 
-.. dropdown:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. code-block:: python
 
@@ -892,8 +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:: :octicon:`code`
-    :color: light
+.. dropdown:: Code
+    :icon: code
 
     .. code-block:: python