Make docs headings consistent.

docs/api.rst

@@ -1,20 +1,23 @@
 .. include:: links.rst
 
-================
+################
 Developers - API
-================
+################
 
+***************************************************
 The *NiPreps* community and contributing guidelines
----------------------------------------------------
+***************************************************
 
 *fMRIPost-template* is a *NiPreps* application, and abides by the
 `NiPreps Community guidelines <https://www.nipreps.org/community/>`__.
 Please, make sure you have read and understood all the documentation
 provided in the `NiPreps portal <https://www.nipreps.org>`__ before
 you get started.
 
+
+***************************************
 Setting up your development environment
----------------------------------------
+***************************************
 
 We believe that *fMRIPost-template* must be free to use, inspect, and critique.
 Correspondingly, you should be free to modify our software to improve it
@@ -27,13 +30,17 @@ As part of such efforts, we maintain some
 `tips and guidelines for developers <https://www.nipreps.org/devs/devenv/>`__
 to help minimize your burden if you want to modify the software.
 
+
+*****************************
 Internal configuration system
------------------------------
+*****************************
 
 .. automodule:: fmripost_template.config
    :members: from_dict, load, get, dumps, to_filename, init_spaces
 
+
+*********
 Workflows
----------
+*********
 
 .. automodule:: fmripost_template.workflows.base

docs/changes.rst

@@ -1,7 +1,7 @@
 .. include:: links.rst
 
-----------
+##########
 What's new
-----------
+##########
 
 .. include:: ../CHANGES.rst

docs/conf.py

@@ -51,6 +51,7 @@
     'sphinx.ext.linkcode',
     'sphinx.ext.napoleon',
     'sphinxarg.ext',  # argparse extension
+    'sphinxcontrib.bibtex',  # to include references in docs
     'nipype.sphinxext.plot_workflow',
 ]
 
@@ -151,6 +152,13 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# -----------------------------------------------------------------------------
+# sphinxcontrib-bibtex
+# -----------------------------------------------------------------------------
+bibtex_bibfiles = ['../src/fmripost_template/data/boilerplate.bib']
+bibtex_style = 'unsrt'
+bibtex_reference_style = 'author_year'
+bibtex_footbibliography_header = ''
 
 # -- Options for HTML output ----------------------------------------------
 

docs/faq.rst

@@ -1,15 +1,17 @@
 .. include:: links.rst
 
-================================
+################################
 FAQ - Frequently Asked Questions
-================================
+################################
 
 .. contents::
     :local:
     :depth: 1
 
+
+*****************
 What is fMRIPost?
------------------
+*****************
 
 fMRIPost workflows are BIDS Apps that ingress fMRI preprocessing derivative datasets.
 They fall under the broader umbrella of NiPost workflows,

docs/index.rst

@@ -6,8 +6,9 @@
 .. include:: links.rst
 .. include:: ../README.rst
 
+********
 Contents
---------
+********
 
 .. toctree::
    :maxdepth: 3

docs/installation.rst

@@ -1,29 +1,34 @@
 .. include:: links.rst
 
-------------
+############
 Installation
-------------
+############
+
 *fMRIPost-template* should be installed using container technologies.
 
 .. code-block:: bash
   docker pull nipreps/fmripost-template:main
 
 
+************************************************
 Containerized execution (Docker and Singularity)
-================================================
+************************************************
+
 *fMRIPost-template* is a *NiPreps* application, and therefore follows some overarching principles
 of containerized execution drawn from the BIDS-Apps protocols.
 For detailed information of containerized execution of *NiPreps*, please visit the corresponding
 `Docker <https://www.nipreps.org/apps/docker/>`__
 or `Singularity <https://www.nipreps.org/apps/singularity/>`__ subsections.
 
+
 External Dependencies
----------------------
-*fMRIPost-template* is written using Python 3.8 (or above), and is based on
+=====================
+
+*fMRIPost-template* is written using Python 3.11 (or above), and is based on
 nipype_.
 
 *fMRIPost-template* requires some other neuroimaging software tools that are
-not handled by the Python's packaging system (Pypi):
+not handled by the Python's packaging system (PyPi):
 
 - FSL_ (version 6.0.7.7)
 - ANTs_ (version 2.5.1)
@@ -33,8 +38,11 @@ not handled by the Python's packaging system (Pypi):
 - `bids-validator <https://github.com/bids-standard/bids-validator>`_ (version 1.14.0)
 - `connectome-workbench <https://www.humanconnectome.org/software/connectome-workbench>`_ (version 1.5.0)
 
+
+***********************************************
 Not running on a local machine? - Data transfer
-===============================================
+***********************************************
+
 If you intend to run *fMRIPost-template* on a remote system, you will need to
 make your data available within that system first.
 

docs/license.rst

@@ -1,11 +1,15 @@
+#######################################
 About the *NiPreps* framework licensing
----------------------------------------
+#######################################
+
 Please check https://www.nipreps.org/community/licensing/ for detailed
 information on the criteria we use to license *fMRIPost-template* and other
 projects of the framework.
 
+
+*******************
 License information
--------------------
+*******************
 Copyright (c) the *NiPreps* Developers.
 
 *fMRIPost-template* is licensed under the Apache License, Version 2.0 (the "License");

docs/links.rst

@@ -1,15 +1,11 @@
 .. _Nipype: https://nipype.readthedocs.io/en/latest/
 .. _BIDS: https://bids.neuroimaging.io/
 .. _`BIDS Derivatives`: https://bids-specification.readthedocs.io/en/stable/05-derivatives/01-introduction.html
-.. _`BEP 011`: https://bids-specification.readthedocs.io/en/bep011/05-derivatives/04-structural-derivatives.html
-.. _`BEP 012`: https://bids-specification.readthedocs.io/en/bep012/05-derivatives/05-functional-derivatives.html
 .. _Installation: installation.html
 .. _workflows: workflows.html
 .. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
 .. _ANTs: https://stnava.github.io/ANTs/
 .. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/
-.. _`submillimeter reconstruction`: https://surfer.nmr.mgh.harvard.edu/fswiki/SubmillimeterRecon
-.. _`mri_robust_template`: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_robust_template
 .. _AFNI: https://afni.nimh.nih.gov/
 .. _GIFTI: https://www.nitrc.org/projects/gifti/
 .. _`Connectome Workbench`: https://www.humanconnectome.org/software/connectome-workbench.html
@@ -20,6 +16,4 @@
 .. _Singularity: https://github.com/singularityware/singularity
 ..  _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/
 .. _TACC: https://www.tacc.utexas.edu/
-.. _tedana: https://github.com/me-ica/tedana
-.. _`T2* workflow`: https://tedana.readthedocs.io/en/latest/generated/tedana.workflows.t2smap_workflow.html#tedana.workflows.t2smap_workflow  # noqa
 .. _`citation boilerplate`: https://www.nipreps.org/intro/transparency/#citation-boilerplates

docs/outputs.rst

@@ -2,9 +2,9 @@
 
 .. _outputs:
 
-------------------------------
+##############################
 Outputs of *fMRIPost-template*
-------------------------------
+##############################
 
 *fMRIPost-template* outputs conform to the :abbr:`BIDS (brain imaging data structure)`
 Derivatives specification (see `BIDS Derivatives`_, along with the
@@ -23,8 +23,9 @@ upcoming `BEP 011`_ and `BEP 012`_).
     Confound time series.
 
 
+******
 Layout
-------
+******
 
 Assuming fMRIPost-template is invoked with::
 
@@ -47,24 +48,26 @@ The log directory contains `citation boilerplate`_ text.
 records metadata recommended by the BIDS standard.
 
 
+**************
 Visual Reports
---------------
+**************
 
 *fMRIPost-template* outputs summary reports,
 written to ``<output dir>/fmripost_template/sub-<label>.html``.
 These reports provide a quick way to make visual inspection of the results easy.
 
 
+**********************************
 Derivatives of *fMRIPost-template*
-----------------------------------
+**********************************
 
 Derivative data are written to
 ``<output dir>/sub-<label>/``.
 The `BIDS Derivatives`_ specification describes the naming and metadata conventions we follow.
 
 
 Functional derivatives
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 Functional derivatives are stored in the ``func/`` subfolder.
 All derivatives contain ``task-<task_label>`` (mandatory) and ``run-<run_index>`` (optional), and
@@ -88,8 +91,9 @@ Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file::
       sub-<label>_[specifiers]_desc-confounds_timeseries.tsv
       sub-<label>_[specifiers]_desc-confounds_timeseries.json
 
+
 Confounds
----------
+=========
 
 *fMRIPost-template* outputs a set of confounds that can be used to denoise the data.
 These are stored in a TSV file (``desc-template_timeseries.tsv``) and a JSON file
@@ -102,8 +106,9 @@ Columns starting with ``template_motion_`` are the raw noise ICA component time
 Columns starting with ``template_orth_motion_`` are the noise ICA component time series,
 after z-scoring and orthogonalization with respect to the signal ICA component time series.
 
+
 Confounds and "carpet"-plot on the visual reports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================================
 
 The visual reports provide several sections per task and run to aid designing
 a denoising strategy for subsequent analysis.

docs/spaces.rst

@@ -6,8 +6,10 @@
    Output spaces are not currently supported.
    fMRIPost-template currently only generates denoised data in MNI152NLin6Asym space.
 
+#####################################################################
 Defining standard and nonstandard spaces where data will be resampled
-=====================================================================
+#####################################################################
+
 The command line interface of *fMRIPost-template* allows resampling the preprocessed data
 onto other output spaces.
 That is achieved using the ``--output-spaces`` argument, where standard and
@@ -20,8 +22,10 @@ nonstandard spaces can be inserted.
 
 .. _TemplateFlow:
 
+**************
 *TemplateFlow*
-""""""""""""""
+**************
+
 *TemplateFlow* is a software library and a repository of neuroimaging templates
 that allows end-user applications such as *fMRIPost-template* to flexibly query and pull
 template and atlas information.
@@ -33,8 +37,10 @@ For more general information about *TemplateFlow*, visit
 `TemplateFlow.org <https://www.templateflow.org>`__.
 
 
+***************
 Standard spaces
-"""""""""""""""
+***************
+
 When using *fMRIPost-template* in a workflow that will investigate effects that span across
 analytical groupings, neuroimagers typically resample their data on to a standard,
 stereotactic coordinate system.
@@ -95,8 +101,11 @@ When specifying surface spaces (e.g., ``fsaverage``), the legacy identifiers fro
 FreeSurfer will be supported (e.g., ``fsaverage5``) although the use of the density
 modifier would be preferred (i.e., ``fsaverage:den-10k`` for ``fsaverage5``).
 
+
+**********************
 Custom standard spaces
-""""""""""""""""""""""
+**********************
+
 To make your custom templates visible by *fMRIPost-template*, and usable via
 the ``--output-spaces`` argument, please store your template under
 *TemplateFlow*'s home directory.
@@ -119,8 +128,11 @@ For further information about how custom templates must be organized and
 corresponding naming, please check `the TemplateFlow tutorials
 <https://www.templateflow.org/python-client/tutorials.html>`__.
 
+
+******************
 Nonstandard spaces
-""""""""""""""""""
+******************
+
 Additionally, ``--output-spaces`` accepts identifiers of spatial references
 that do not generate *standardized* coordinate spaces:
 
@@ -140,8 +152,11 @@ that do not generate *standardized* coordinate spaces:
 
 Modifiers are not allowed when providing nonstandard spaces.
 
-Preprocessing blocks depending on standard templates
-""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+*****************************************************
+Postprocessing blocks depending on standard templates
+*****************************************************
+
 Some modules of the pipeline (e.g., the generation of HCP compatible
 *grayordinates* files, or the *fieldmap-less* distortion correction)
 operate in specific template spaces.