From edba34d0e1b59379f729ee953a1ced89f86b629d Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Wed, 10 Jan 2024 12:54:21 -0500 Subject: [PATCH 1/8] [skip ci] Draft a glossary. --- docs/conf.py | 7 +++++++ docs/glossary.rst | 13 +++++++++++++ docs/workflows.rst | 3 ++- pyproject.toml | 1 + 4 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 docs/glossary.rst diff --git a/docs/conf.py b/docs/conf.py index 9ce87527a..acc80a373 100644 --- a/docs/conf.py +++ b/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,12 @@ bibtex_reference_style = "author_year" bibtex_footbibliography_header = "" +# -- +# hoverxref +# -- +hoverxref_auto_ref = True +hoverxref_mathjax = True + def setup(app): """Add extra formatting files.""" diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..cdd515c12 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,13 @@ +.. include:: links.rst + +.. glossary:: + + ASL + Arterial spin labeling. + + 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} diff --git a/docs/workflows.rst b/docs/workflows.rst index aab72b1d8..066db75d6 100644 --- a/docs/workflows.rst +++ b/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 `, the pairs of labeled and control images are subtracted: +After :ref:`preprocessing `, the pairs of labeled and control images are subtracted +to produce a :term:`Delta-M` time series: .. math:: \Delta{M} = M_{C} - M_{L} diff --git a/pyproject.toml b/pyproject.toml index 62f0f26f8..30aae8f18 100644 --- a/pyproject.toml +++ b/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", From 6fcaebde2da34fc181f70fae977924cf1450b441 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Wed, 10 Jan 2024 12:55:54 -0500 Subject: [PATCH 2/8] Add term to roles. --- docs/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index acc80a373..312b0a1f4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -336,6 +336,12 @@ # -- hoverxref_auto_ref = True hoverxref_mathjax = True +hoverxref_roles = [ + "numref", + "confval", + "setting", + "term", +] def setup(app): From ae2d30af0e64a9b40b7f32420403b09fc1922149 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Wed, 10 Jan 2024 12:57:50 -0500 Subject: [PATCH 3/8] [skip ci] Add term. --- docs/glossary.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/glossary.rst b/docs/glossary.rst index cdd515c12..e9affa801 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -5,6 +5,9 @@ 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. From 1cbb15905336d0001c1328f1ce88bb1d516656db Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Fri, 12 Jan 2024 14:02:53 -0500 Subject: [PATCH 4/8] [skip ci] Work on glossary. --- docs/conf.py | 1 + docs/glossary.rst | 2 +- docs/links.rst | 2 ++ 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 312b0a1f4..ebcc656b3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -341,6 +341,7 @@ "confval", "setting", "term", + "footcite", ] diff --git a/docs/glossary.rst b/docs/glossary.rst index e9affa801..65816839e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -8,7 +8,7 @@ CBF Cerebral blood flow. ASLPrep provides CBF results in mL/100 g/min. - Delta-M + |Delta-M| :math:`\Delta{M}` is a time series produced by subtracting labelled volumes in the ASL time series from the associated control volumes. diff --git a/docs/links.rst b/docs/links.rst index c85764037..b1548b139 100644 --- a/docs/links.rst +++ b/docs/links.rst @@ -12,3 +12,5 @@ .. _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}` From 888c06dd8ad70af20ef8df6fc2bce3378a257bed Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Fri, 12 Jan 2024 14:07:01 -0500 Subject: [PATCH 5/8] Update workflows.rst --- docs/workflows.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflows.rst b/docs/workflows.rst index 066db75d6..a74e4eeb7 100644 --- a/docs/workflows.rst +++ b/docs/workflows.rst @@ -289,7 +289,7 @@ 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 `, the pairs of labeled and control images are subtracted -to produce a :term:`Delta-M` time series: +to produce a :term:`|Delta-M|` time series: .. math:: \Delta{M} = M_{C} - M_{L} From fc8d7306424e3272ac70b2368cc03fc2ab4bface Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Fri, 12 Jan 2024 14:10:03 -0500 Subject: [PATCH 6/8] [skip ci] define lambda --- docs/glossary.rst | 10 ++++++++++ docs/links.rst | 1 + docs/workflows.rst | 3 +-- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/glossary.rst b/docs/glossary.rst index 65816839e..5d7c722d2 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -14,3 +14,13 @@ .. 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:: \ No newline at end of file diff --git a/docs/links.rst b/docs/links.rst index b1548b139..1e8878862 100644 --- a/docs/links.rst +++ b/docs/links.rst @@ -14,3 +14,4 @@ .. _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/ .. |Delta-M| replace:: :math:`\Delta{M}` +.. |lambda| replace:: :math:`\lambda` diff --git a/docs/workflows.rst b/docs/workflows.rst index a74e4eeb7..83973ac56 100644 --- a/docs/workflows.rst +++ b/docs/workflows.rst @@ -314,8 +314,7 @@ 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|` :math:`\alpha` : Labeling efficiency. This may be directly encoded in the ASL file's sidecar file with the ``LabelingEfficiency`` field. From d9a73582abe5ff312215cfa8e2f06145bf8f36c6 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Fri, 12 Jan 2024 14:20:44 -0500 Subject: [PATCH 7/8] [skip ci] Try this. --- docs/workflows.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflows.rst b/docs/workflows.rst index 83973ac56..312642e6a 100644 --- a/docs/workflows.rst +++ b/docs/workflows.rst @@ -314,7 +314,7 @@ model :footcite:p:`alsop_recommended_2015`. :math:`\tau` : Labeling duration, in seconds. - :term:`|lambda|` + |:term:`lambda`| :math:`\alpha` : Labeling efficiency. This may be directly encoded in the ASL file's sidecar file with the ``LabelingEfficiency`` field. From c45b251dc6ffa0f7d3614004474648e6bbd02d2b Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Fri, 12 Jan 2024 14:25:05 -0500 Subject: [PATCH 8/8] [skip ci] try that --- docs/workflows.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/workflows.rst b/docs/workflows.rst index 312642e6a..06b86e67b 100644 --- a/docs/workflows.rst +++ b/docs/workflows.rst @@ -314,7 +314,9 @@ model :footcite:p:`alsop_recommended_2015`. :math:`\tau` : Labeling duration, in seconds. - |:term:`lambda`| + :term:`lambda <|lambda|>` + + :term:`|lambda| ` :math:`\alpha` : Labeling efficiency. This may be directly encoded in the ASL file's sidecar file with the ``LabelingEfficiency`` field.