Merge pull request #1367 from nipreps/doc/docker-execution

DOC: Reorganize documentation and redirect to nipreps docs

Author: oesteban

docs/source/docker.rst

@@ -14,8 +14,7 @@ Contents
 
    about
    install
-   running
-   docker
+   usage
    measures
    reports
    workflows

docs/source/index.rst

@@ -1,28 +1,22 @@
 
-Installation
-************
-Containerized versions
-----------------------
-If you have Docker installed, the quickest way to get ``mriqc`` to work
-is following :ref:`the running with docker guide <docker>`.
-
-We recommend trying containerized versions first to avoid installation
-issues.
-MRIQC uses bleeding-edge (oftentimes unreleased) versions of
-``nipype`` and ``niworkflows`` and "bare-metal" installations can
-be hard.
-Nonetheless, we offer support on our `github repository
-<https://github.com/nipreps/mriqc/issues>`_.
-
+Installing *MRIQC*
+******************
+*MRIQC* is a *NiPreps* (`www.nipreps.org <https://nipreps.org>`__)
+*BIDS App* [BIDSApps]_.
+As such, *MRIQC* can be installed manually (*Bare-metal installation*,
+see below) or containerized.
+For containerized execution with *Docker* or *Singularity*, please
+follow the documentation on the *NiPreps* site
+(`introduction <https://www.nipreps.org/apps/framework/>`__).
 
 "Bare-metal" installation
 -------------------------
-If, for some reason, you really need a bare-metal installation,
-MRIQC can be installed as follows.
+If, for some reason, you really need a custom installation,
+*MRIQC* can be installed as follows.
 First, please make sure you have the execution system dependencies
 installed (see below).
 Second, the latest development version of MRIQC can be installed from
-github using ``pip`` on a Python 3 environment: ::
+github using ``pip`` on a Python 3 environment:
 
   python -m pip install -U mriqc
 
@@ -55,8 +49,6 @@ github using ``pip`` on a Python 3 environment: ::
 
         $ sed -i 's/\(backend *: \).*$/\1Agg/g' $( python -c "import matplotlib; print(matplotlib.matplotlib_fname())" )
 
-
-
 Execution system dependencies
 .............................
 If you are using a a `Neurodebian <http://neuro.debian.net/>`_ Linux distribution,

docs/source/install.rst

@@ -3,18 +3,34 @@
 
 Running *MRIQC*
 ***************
-.. tip::
-     Try MRIQC online on `OpenNeuro <https://www.openneuro.org/>`_ - without
-     installation!
-
-MRIQC is a `BIDS-App <http://bids-apps.neuroimaging.io/>`_ [BIDSApps]_,
+*MRIQC* is a `BIDS-App <http://bids-apps.neuroimaging.io/>`_ [BIDSApps]_,
 and therefore it inherently understands the :abbr:`BIDS (brain
-imaging data structure)` standard [BIDS]_ and follows the
-BIDS-Apps standard command line interface::
+imaging data structure)` standard [BIDS]_.
+Before moving forward, please make sure to have read and understood
+*NiPreps*'s
+`introductory documentation <https://www.nipreps.org/apps/framework/>`__).
+
+Containerized execution with *Docker* and *Singularity*/*Apptainer*
+-------------------------------------------------------
+For containerized execution with *Docker* or *Singularity*/*Apptainer*, please
+follow the documentation on the *NiPreps* site, which contains
+tip and troubleshooting guidelines for both
+`Docker <https://www.nipreps.org/apps/docker/>`__, and
+`Singularity or Apptainer <https://www.nipreps.org/apps/singularity/>`__.
+In addition to container-specific guidelines, the documentation
+also includes specific
+`help for processing DataLad-managed datasets <https://www.nipreps.org/apps/datalad/>`__.
+
+The rest of this documentation page applies to both *bare-metal*
+and containerized execution modes.
+
+A *BIDS Apps* command line interface
+------------------------------------
+*MRIQC* follows the *BIDS Apps* standard command line interface::
 
   mriqc bids-root/ output-folder/ participant
 
-That simple command runs MRIQC on all the *T1w* and *BOLD* images found
+That simple command runs *MRIQC* on all the *T1w* and *BOLD* images found
 under the BIDS-compliant folder ``bids-root/``.
 The last ``participant`` keyword indicates that the first level analysis
 is run. (i.e. extracting the :abbr:`IQMs (image quality metrics)` from the
@@ -70,6 +86,22 @@ in :ref:`The MRIQC Reports <reports>`.
     In the ``group`` level, the :abbr:`IQMs (image quality metrics)` extracted in
     first place are combined in a table and the group reports are generated.
 
+*MRIQC* can fetch data in *DataLad* datasets
+--------------------------------------------
+As of version 22.0.3, *MRIQC* bundles *DataLad*, enabling automatic
+data fetching in *DataLad* datasets.
+Employing this feature in containerized environments may lead to
+somewhat obscure errors (see, for example,
+`nipreps/mriqc#1307 <https://github.com/nipreps/mriqc/issues/1307>`__).
+If you intend to use *DataLad* datasets, please read carefully
+*NiPreps*' `help for processing DataLad-managed datasets <https://www.nipreps.org/apps/datalad/>`__.
+
+Alternatively, this feature can be disabled by adding
+``--no-datalad-get`` to the command line.
+This will separate *DataLad* management from *MRIQC*'s operation,
+which can be an effective way of debugging issues and averting
+erroneous conditions.
+
 Command line interface
 ----------------------
 .. argparse::
@@ -80,14 +112,10 @@ Command line interface
 
 Running mriqc on HPC clusters
 -----------------------------
-Singularity containers
-......................
-Requesting resources
-....................
 We have profiled cores and memory usages with the *resource profiler*
-tool of nipype.
+tool of *Nipype*.
 
-An MRIQC run of one subject (from the ABIDE) dataset, containing only one
+An *MRIQC* run of one subject (from the ABIDE) dataset, containing only one
 run, one BOLD task (resting-state) yielded the following report:
 
   .. raw:: html
@@ -117,5 +145,3 @@ on ds030 of OpenfMRI:
   .. [BIDS] `Brain Imaging Data Structure <http://bids.neuroimaging.io/>`_
   .. [BIDSApps] `BIDS-Apps: portable neuroimaging pipelines that understand BIDS
      datasets <http://bids-apps.neuroimaging.io/>`_
-
-.. include:: license.rst