Workaround docs build problem.

Include alternative index workaround.

docs/src/conf.py

@@ -217,6 +217,12 @@ def _dotv(version):
 autopackage_name = ["iris"]
 autoclass_content = "both"
 modindex_common_prefix = ["iris"]
+# Note: the iris.ugrid mesh classes currently have multiple API references, due to
+#  "cross-linked" references in the legacy "iris.experimental.ugrid" API.
+# This causes an index warning, which breaks the build due to building with -W.
+# So turn that warning off.
+# TODO: remove this when we remove iris.experimental.ugrid
+autodoc_suppress_warnings = ["index"]
 
 # -- apidoc extension ---------------------------------------------------------
 # See https://github.com/sphinx-contrib/apidoc

lib/iris/experimental/ugrid.py

@@ -32,6 +32,16 @@
 from ..ugrid.save import save_mesh
 from ..ugrid.utils import recombine_submeshes
 
+# NOTE: the duplicate API references for Mesh, MeshCoord and Connectivity here cause
+# Sphinx to issue a warning about duplicate index entries.
+# (e.g. "WARNING: duplicate object description of iris.ugrid.mesh.Mesh, other instance
+#       in generated/api/iris.experimental.ugrid, use :no-index: for one of them"
+# )
+# For some reason, this only happens for the classes, and not the functions.
+# Currently ignored, by setting autodoc_suppress_warnings = ["index"] in conf.py
+# TODO: remove that when this module is removed.
+
+
 __all__ = [
     "Connectivity",
     "Mesh",