docs: add :user: extlinks convenience

Author: bjlittle

docs/src/common_links.inc

@@ -47,6 +47,7 @@
 .. _iris-esmf-regrid: https://github.com/SciTools-incubator/iris-esmf-regrid
 .. _netCDF4: https://github.com/Unidata/netcdf4-python
 .. _SciTools Contributor's License Agreement (CLA): https://cla-assistant.io/SciTools/
+.. _extlinks: https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 
 
 .. comment

docs/src/conf.py

@@ -288,6 +288,7 @@ def _dotv(version):
         "https://github.com/SciTools/iris/discussions/%s",
         "Discussion #%s",
     ),
+    "user": ("https://github.com/%s", "@%s"),
 }
 
 # -- Doctest ("make doctest")--------------------------------------------------

docs/src/developers_guide/documenting/whats_new_contributions.rst

@@ -82,6 +82,18 @@ The required content, in order, is as follows:
 
     .. _@tkknight: https://github.com/tkknight
 
+  .. hint::
+
+    Alternatively adopt the ``:user:`` `extlinks`_ convenience instead.
+
+    For example to reference the ``github`` user ``tkknight`` simply use
+    :literal:`:user:\`tkknight\``.
+
+    This will be rendered as :user:`tkknight`.
+
+    In addition, there is now no need to add a full reference to the user within
+    the documentation.
+
 * A succinct summary of the new/changed behaviour.
 
 * Context to the change. Possible examples include: what this fixes, why
@@ -143,3 +155,4 @@ users.  To achieve this several categories may be used.
 **💼 Internal**
   Changes to any internal or development related topics, such as testing,
   environment dependencies etc.
+

docs/src/whatsnew/latest.rst

@@ -86,6 +86,9 @@ This document explains the changes made to Iris for this release
 
 #. `@tkknight`_ added a gallery carousel to the documentation homepage. (:pull:`6884`)
 
+#. :user:`bjlittle` added the ``:user:`` `extlinks`_ ``github`` user convenience.
+   (:pull:`6931`)
+
 
 💼 Internal
 ===========