Draft a glossary

docs/conf.py

@@ -47,6 +47,7 @@
 # Add any Sphinx extension module names here, as strings.
 # They can be extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
 extensions = [
+    "hoverxref.extension",
     "nbsphinx",
     "nipype.sphinxext.apidoc",
     "nipype.sphinxext.plot_workflow",
@@ -330,6 +331,19 @@
 bibtex_reference_style = "author_year"
 bibtex_footbibliography_header = ""
 
+# --
+# hoverxref
+# --
+hoverxref_auto_ref = True
+hoverxref_mathjax = True
+hoverxref_roles = [
+    "numref",
+    "confval",
+    "setting",
+    "term",
+    "footcite",
+]
+
 
 def setup(app):
     """Add extra formatting files."""

docs/glossary.rst

@@ -0,0 +1,26 @@
+.. include:: links.rst
+
+.. glossary::
+
+   ASL
+      Arterial spin labeling.
+
+   CBF
+      Cerebral blood flow. ASLPrep provides CBF results in mL/100 g/min.
+
+   |Delta-M|
+      :math:`\Delta{M}` is a time series produced by subtracting labelled volumes in the ASL time
+      series from the associated control volumes.
+
+      .. math::
+         \Delta{M} = M_{C} - M_{L}
+
+   |lambda|
+      Brain-blood partition coefficient.
+      Set to 0.9 g/mL :footcite:p:`alsop_recommended_2015`.
+
+
+References
+==========
+
+.. footbibliography::

docs/links.rst

@@ -12,3 +12,6 @@
 .. _Nipype: http://nipype.readthedocs.io/en/latest/
 .. _Singularity: https://github.com/singularityware/singularity
 .. _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/
+
+.. |Delta-M| replace:: :math:`\Delta{M}`
+.. |lambda| replace:: :math:`\lambda`

docs/workflows.rst

@@ -288,7 +288,8 @@ ASL data consist of multiple pairs of labeled and control images.
 In the absence of M0 images or an M0 estimate provided in the metadata,
 the average of control images is used as the reference image.
 
-After :ref:`preprocessing <asl_preproc>`, the pairs of labeled and control images are subtracted:
+After :ref:`preprocessing <asl_preproc>`, the pairs of labeled and control images are subtracted
+to produce a :term:`|Delta-M|` time series:
 
 .. math::
     \Delta{M} = M_{C} - M_{L}
@@ -313,8 +314,9 @@ model :footcite:p:`alsop_recommended_2015`.
 
    :math:`\tau` : Labeling duration, in seconds.
 
-   :math:`\lambda` : Brain-blood partition coefficient.
-   Set to 0.9 g/mL :footcite:p:`alsop_recommended_2015`.
+   :term:`lambda <|lambda|>`
+
+   :term:`|lambda| <lambda>`
 
    :math:`\alpha` : Labeling efficiency.
    This may be directly encoded in the ASL file's sidecar file with the ``LabelingEfficiency`` field.

pyproject.toml

@@ -60,6 +60,7 @@ doc = [
     "recommonmark",
     "sphinx >= 6.2.1",
     "sphinx-argparse",
+    "sphinx-hoverxref",
     "sphinx-markdown-tables",
     "sphinx_rtd_theme >= 1.2.2",
     "sphinxcontrib-apidoc",