Adopt Diataxis

.lycheeignore

@@ -4,16 +4,17 @@ file:///
 # DEAD : legacy in various old whatsnews
 https://biggus.readthedocs.io
 
-# unkown problem, works in browser : used in further_topics/ugrid/data_model
+# unknown problem, works in browser : used in
+#  docs/src/user_manual/explanation/mesh_data_model.rst
 https://doi.org/10.3390/jmse2010194
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 https://effbot.org
 
 # nonfunctional, found in some code examples
 https://foo/
 
-# DEAD, todo:remove, used in docs/src/further_topics/ugrid/data_model.rst
+# DEAD, todo:remove, used in docs/src/user_manual/explanation/mesh_data_model.rst
 https://ibm-design-language.eu-de.mybluemix.net/design/language/resources/color-library
 
 # DEAD, legacy in whatsnew/1.4.rst
@@ -45,14 +46,14 @@ https://stickler-ci.com
 # DEAD, todo:remove, used in lib/iris/symbols.py
 https://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 # unkown problem, works in browser : used in docs/src/index.rst
 https://www.flaticon.com
 
 # nonfunctional example, used in lib/iris/io/__init__.py
 https://www.thing.com
 
-# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# DEAD, todo:remove, used in docs/src/user_manual/tutorial/plotting_a_cube.rst
 https://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_updates.html
 
 # nonfunctional, found in some code examples

docs/gallery_code/general/plot_global_map.py

@@ -2,6 +2,11 @@
 Quickplot of a 2D Cube on a Map
 ===============================
 
+.. how-to:: Quickplot of a 2D Cube on a Map
+   :tags: topic_plotting
+
+   Code demonstrating basic ``iris.quickplot`` use.
+
 This example demonstrates a contour plot of global air temperature. The plot
 title and the labels for the axes are automatically derived from the metadata.
 

docs/src/_templates/tags_links.need

@@ -0,0 +1,11 @@
+{# Render plain clickable text links for each tag #}
+{% if tags %}
+:strong:`Tags:` {{ " " }} {%- for t in tags -%}
+  {%- if t and t.startswith('topic_') -%}
+    :ref:`{{ t }} <{{ t }}>`
+  {%- else -%}
+    {{ t }}
+  {%- endif -%}
+  {%- if not loop.last %} | {% endif -%}
+{%- endfor %}
+{% endif %}

docs/src/conf.py

@@ -163,6 +163,8 @@ def _dotv(version):
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
+    "sphinx_needs",
+    "user_manual_directives",
 ]
 
 if skip_api == "1":
@@ -441,3 +443,57 @@ def reset_modules(gallery_conf, fname):
     "section": "Section %s",
     "table": "Table %s",
 }
+
+# -- sphinx-needs config ------------------------------------------------------
+# See https://sphinx-needs.readthedocs.io/en/latest/configuration.html
+
+# TODO: namespace these types as Diataxis for max clarity?
+needs_types = [
+    {
+        "directive": "tutorial",
+        "title": "Tutorial",
+        "prefix": "",
+        "color": "",
+        "style": "node",
+    },
+    {
+        "directive": "how-to",
+        "title": "How To",
+        "prefix": "",
+        "color": "",
+        "style": "node",
+    },
+    {
+        "directive": "explanation",
+        "title": "Explanation",
+        "prefix": "",
+        "color": "",
+        "style": "node",
+    },
+    {
+        "directive": "reference",
+        "title": "Reference",
+        "prefix": "",
+        "color": "",
+        "style": "node",
+    },
+]
+# The layout whenever a 'need item' directive is used. I.e. at the top of each
+#  user manual page.
+needs_default_layout = "focus"
+# # IDs must be used in needtables, as the only way to link to the item. Using
+# #  the title makes for the most readable / least jarring links.
+# needs_id_from_title = True
+# The `tags_links` jinja template displays a list of tags where every topic_*
+#  tag is a link to the relevant section in user_manual/index.rst.
+needs_template_folder = "_templates"
+needs_global_options = {
+    "post_template": {"default": "tags_links"},
+}
+
+from sphinx_needs.data import NeedsCoreFields
+
+# Known bug in sphinx-needs pre v6.0.
+#  https://github.com/useblocks/sphinx-needs/issues/1420
+if "allow_default" not in NeedsCoreFields["post_template"]:
+    NeedsCoreFields["post_template"]["allow_default"] = "str"