Restructure documentation according to Diataxis

.readthedocs.yml

@@ -5,15 +5,13 @@
 # Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.10"
-    # You can also specify other tool versions:
-    # nodejs: "16"
-    # rust: "1.55"
-    # golang: "1.17"
+    # Capped at 3.12: docs/requirements.txt installs rabies so that
+    # sphinxcontrib-programoutput can run `rabies --help` at build time, and
+    # rabies requires Python <3.13.
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -26,4 +24,4 @@ formats:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: docs/requirements.txt
+   - requirements: docs/requirements.txt

README.md

@@ -13,28 +13,26 @@ The preprocessing workflow regroups essential fMRI preprocessing steps prior to
 - head motion correction
 - susceptibility distortion correction
 - resampling to native or common space
-- brain parcellation
 - slice timing correction (optional)
 - despiking (optional)
 - visual assessment of registration for quality control
 
 ### Confound correction
-Following preprocessing, a range of strategies to correct fMRI confounds (e.g. motion) can then be conducted within RABIES:
-- linear detrending
+Following preprocessing, RABIES provides a highly-customizable confound correction pipeline regrouping several common strategies:
+- frame censoring (or scrubbing)
 - confound regression (with several options for nuisance regressors)
 - frequency filtering (highpass, lowpass, bandpass)
-- frame censoring (or scrubbing)
 - ICA-AROMA
 - spatial smoothing
 
 ### Analysis
-Simple resting-state connectivity analyses are made available after preprocessing and confound correction. RABIES also provides a 'data diagnosis' workflow, which generates several indices of data quality and potential confounds, and conversaly, aims to improve the correction of confounds and transparency with regards to data quality:
+Simple resting-state connectivity analyses are made available after preprocessing and confound correction: 
 - seed-based functional connectivity
 - whole-brain connectivity matrix
 - group-ICA
 - dual regression
-- data diagnosis
 
+Importantly, the analysis stage is also complemented by a data quality assessment report (executed with `--data_diagnosis`), which generates several indices of data quality and potential confounds, with the aim of improving preprocessing strategies, data interpretation and scientific transparency.
 
 ## Notes on software design
 
@@ -44,7 +42,7 @@ Simple resting-state connectivity analyses are made available after preprocessin
 - open source code <https://github.com/CoBrALab/RABIES>
 - standardized input data format with [BIDS](https://bids.neuroimaging.io/)
 - easily shared, automatically-generated visual outputs for quality control
-- containerized distribution of the software hosted on [Docker Hub](https://hub.docker.com/r/gabdesgreg/rabies) which can be downloaded via Docker and Apptainer platforms
+- containerized distribution of the software through Docker/Apptainer, and conveniently installed from our [Github](https://github.com/CoBrALab/RABIES/pkgs/container/rabies) or [Docker Hub](https://hub.docker.com/r/gabdesgreg/rabies) servers.
 
 ## Citation
 
@@ -56,12 +54,8 @@ Simple resting-state connectivity analyses are made available after preprocessin
 The [RABIES license](https://github.com/CoBrALab/RABIES/blob/master/LICENSE) allows for uses in academic and educational environments only. Commercial use requires a commercial license from CoBrALab <contact@cobralab.ca>, <http://cobralab.ca>
 
 ## Acknowledgements
-This software was developped by the [CoBrALab](https://cobralab.ca/), located at the Cerebral Imaging Center of the Douglas Mental Health University Institute, Montreal, Canada, in affiliation with McGill University, Montreal, Canada. This work was supported by funding from Healthy Brains, Healthy Lives (HBHL), the Fonds de recherche du Québec - Santé (FRQS) and - Nature et technologies (FRQNT), and the Natural Sciences and Engineering Research Council (NSERC) of Canada. [fMRIPrep](https://fmriprep.org/en/stable/) was an important inspirational source for this project, in particular with regards to best practices for software reproducibility and code design using Nipype. We also thank the organizers of [BrainHack School Montreal](https://school.brainhackmtl.org/), which guided the initial steps of this project in 2018.
+This software was developed by the [CoBrALab](https://cobralab.ca/), located at the Cerebral Imaging Center of the Douglas Mental Health University Institute, Montreal, Canada, in affiliation with McGill University, Montreal, Canada. This work was supported by funding from Healthy Brains, Healthy Lives (HBHL), the Fonds de recherche du Québec - Santé (FRQS) and - Nature et technologies (FRQNT), and the Natural Sciences and Engineering Research Council (NSERC) of Canada. [fMRIPrep](https://fmriprep.org/en/stable/) was an important inspirational source for this project, in particular with regards to best practices for software reproducibility and code design using Nipype. We also thank the organizers of [BrainHack School Montreal](https://school.brainhackmtl.org/), which guided the initial steps of this project in 2018.
 
 
 ## Ask for help
 If you need support in using the software or experience issues that are not documented, we'll provide support on the [Github discussion](https://github.com/CoBrALab/RABIES/discussions).
-
-## Contributing to RABIES
-
-**Read our dedicated [documentation](https://rabies.readthedocs.io/en/latest/contributing.html)**

docs/_static/custom.css

@@ -0,0 +1,92 @@
+/* ---------------------------------------------------------------------------
+   Fully expanded sidebar navigation
+
+   `collapse_navigation: False` makes Sphinx emit the complete toctree into
+   every page, but the RTD theme still hides most of it in CSS, so the nav
+   only opens along the branch you are currently on. See
+   https://github.com/readthedocs/sphinx_rtd_theme/issues/455
+
+   Three theme rules do the hiding:
+     .wy-menu-vertical li ul                            { display: none }
+     .wy-menu-vertical .toctree-lN.current .toctree-lM>ul { display: none }
+     .wy-menu-vertical li.current ul                    { display: block }
+
+   The second is 4 classes deep, so !important is the honest way to beat it
+   without duplicating that whole selector chain.
+   --------------------------------------------------------------------------- */
+.wy-menu-vertical li ul {
+    display: block !important;
+}
+
+/* With nothing left to expand, the disclosure arrows are misleading: clicking
+   one would appear to do nothing. */
+.wy-menu-vertical li button.toctree-expand {
+    display: none !important;
+}
+
+/* The theme paints nested entries #404040 (near-black). That only works
+   because it shows them exclusively on the current branch, where the
+   background is light. Now that every branch is open, off-branch entries sit
+   on the dark sidebar and that colour is illegible — so give them the same
+   light-on-dark treatment the top-level entries get.
+
+   `.wy-menu-vertical li.current a` ties with this selector on specificity
+   (both 2 classes + 2 elements), and custom.css loads later, so this would
+   otherwise also repaint the current branch — where the background *is*
+   light. The rule below puts the dark text back there. */
+.wy-menu-vertical li.toctree-l2 a,
+.wy-menu-vertical li.toctree-l3 a,
+.wy-menu-vertical li.toctree-l4 a {
+    color: #d9d9d9;
+}
+
+.wy-menu-vertical li.current li.toctree-l2 a,
+.wy-menu-vertical li.current li.toctree-l3 a,
+.wy-menu-vertical li.current li.toctree-l4 a {
+    color: #404040;
+}
+
+/* Indent each level and taper the size, so the hierarchy still reads at a
+   glance without the disclosure arrows to mark it. */
+.wy-menu-vertical li.toctree-l2 a {
+    padding-left: 2.427em;
+}
+
+.wy-menu-vertical li.toctree-l3 a {
+    padding-left: 3.5em;
+    font-size: 0.85em;
+}
+
+.wy-menu-vertical li.toctree-l4 a {
+    padding-left: 4.5em;
+    font-size: 0.8em;
+}
+
+/* The RTD theme caps content width at 800px, which is cramped for the
+   parcellation tables, --help output and the wider figures. */
+.wy-nav-content {
+    max-width: 1000px;
+}
+
+/* Keep wide content (help output, tables, diagrams) inside its own scroll
+   region rather than forcing the page to scroll horizontally. */
+.rst-content div[class^='highlight'] pre,
+.rst-content table.docutils {
+    overflow-x: auto;
+}
+
+/* sphinx-design cards inherit an RTD margin that double-spaces the grids. */
+.rst-content .sd-card {
+    margin-bottom: 0;
+}
+
+.rst-content .sd-card .sd-card-title {
+    font-weight: 600;
+}
+
+/* Definition lists are used heavily for parameter descriptions; give the term
+   enough weight to scan against the body text. */
+.rst-content dl:not(.docutils) > dt,
+.rst-content dl.simple > dt {
+    font-weight: 600;
+}

docs/_static/refs.bib

@@ -969,3 +969,34 @@ @ARTICLE{Biswal1995-vh
   keywords  = "Functional connectivity;FC and Brain Networks;RABIES
                documentation"
 }
+
+@ARTICLE{Dorr2008-cc,
+  title    = "High resolution three-dimensional brain atlas using an average
+              magnetic resonance image of 40 adult {C57Bl}/{6J} mice",
+  author   = "Dorr, A E and Lerch, J P and Spring, S and Kabani, N and
+              Henkelman, R M",
+  journal  = "Neuroimage",
+  volume   =  42,
+  number   =  1,
+  pages    = "60--69",
+  abstract = "Detailed anatomical atlases can provide considerable interpretive
+              power in studies of both human and rodent neuroanatomy. Here we
+              describe a three-dimensional atlas of the mouse brain, manually
+              segmented into 62 structures, based on an average of 32 mum
+              isotropic resolution T(2)-weighted, within skull images of forty
+              12 week old C57Bl/6J mice, scanned on a 7 T scanner. Individual
+              scans were normalized, registered, and averaged into one volume.
+              Structures within the cerebrum, cerebellum, and brainstem were
+              painted on each slice of the average MR image while using
+              simultaneous viewing of the coronal, sagittal and horizontal
+              orientations. The final product, which will be freely available to
+              the research community, provides the most detailed MR-based,
+              three-dimensional neuroanatomical atlas of the whole brain yet
+              created. The atlas is furthermore accompanied by ancillary
+              detailed descriptions of boundaries for each structure and
+              provides high quality neuroanatomical details pertinent to MR
+              studies using mouse models in research.",
+  month    =  aug,
+  year     =  2008,
+  language = "en"
+}