docs: refactor datalad requirements

The DataLad access requirements are moved to a separate section, which
is referenced in short paragraph by dataset generation and access
sections.

docs/source/user/datalad-access.rst

@@ -8,23 +8,11 @@ datasets which have already been created and made available, most
 likely on local infrastructure. Dataset generation is described in
 the previous section, :ref:`dl-generate`.
 
-Requirements
-^^^^^^^^^^^^
-
-Cloning datasets generated with the ICF tooling and accessing the ICF
-store requires `DataLad`_ with `Datalad-Next`_ extension installed.
-You can find instructions for installing DataLad on your operating
-system in the `DataLad Handbook`_.  `Datalad-Next`_ can be installed
-with `pip`_ [1]_.
-
-.. _datalad: https://www.datalad.org/
-.. _datalad-next: https://docs.datalad.org/projects/next
-.. _datalad handbook: https://handbook.datalad.org/intro/installation.html
-.. _pip: https://pip.pypa.io/en/stable/
-
-Obtaining data hosted in the ICF store requires access credentials for
-a given study, issued by the ICF. DataLad acts only as a client
-software. See :ref:`dl-credentials` for details.
+This workflow uses DataLad with DataLad-Next extension (see
+:ref:`dl-requirements`). DataLad datasets index data in their original
+(ICF) location. Obtaining data hosted in the ICF store requires access
+credentials for a given study, issued by the ICF. DataLad acts only as
+a client software. See :ref:`dl-credentials` for details.
 
 Clone & get
 ^^^^^^^^^^^
@@ -34,7 +22,7 @@ location, it can be cloned with DataLad from a URL containing the
 following components:
 
 * a set of configuration parameters, always constant
-* store base URL (e.g., ``file:///data/group/groupname/local_dicom_store``) [2]_
+* store base URL (e.g., ``file:///data/group/groupname/local_dicom_store``) [1]_
 * study ID (e.g., ``my-study``)
 * visit ID (e.g., ``P000123``)
 * a file name suffix / template, ``_annex{{annex_key}}`` (verbatim), always constant
@@ -70,12 +58,7 @@ convenience features DataLad adds on top of this.
 
 .. rubric:: Footnotes
 
-.. [1] To install software with pip, run a call such as the one below
-       in your favourite `virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_::
-
-         python -m pip install datalad-next
-
-.. [2] Examples use ``file://`` URLs, given that the datasets are most
+.. [1] Examples use ``file://`` URLs, given that the datasets are most
        likely to be generated on institute-local infrastructure. Other
        protocoles (e.g. ``https://`` or ``ssh://``) can be substituted
        depending on the particular setup, without affecting the URL

docs/source/user/datalad-generate.rst

@@ -15,22 +15,11 @@ allow raw data versioning, integrate with existing workflows, and
 enable logical transformations of the DICOM folder structure - see
 :ref:`dl-advanced` for examples of the latter.
 
-Software requirements
-^^^^^^^^^^^^^^^^^^^^^
-
-Accessing the ICF store requires `DataLad`_ with `Datalad-Next`_
-extension installed.  You can find instructions for installing DataLad
-on your operating system in the `DataLad Handbook`_.  `Datalad-Next`_
-can be installed with `pip`_ [1]_.
-
-.. _datalad: https://www.datalad.org/
-.. _datalad-next: https://docs.datalad.org/projects/next
-.. _datalad handbook: https://handbook.datalad.org/intro/installation.html
-.. _pip: https://pip.pypa.io/en/stable/
-
-Dataset generation workflow (all steps after the initial download)
-uses the INM-ICF tools, which are packaged as a Singularity container;
-see :ref:`container`.
+The workflow described below uses DataLad with DataLad-Next extension
+for initial DICOM download and the INM-ICF tools packaged as a
+Singularity container for subsequent steps (see
+:ref:`dl-requirements`). ICF access credentials are required (see
+:ref:`dl-credentials`).
 
 Obtain the tarball
 ^^^^^^^^^^^^^^^^^^
@@ -140,10 +129,3 @@ representation in ``*XDLRA*`` files.
 The local store can be used as a DataLad entry point for obtaining the
 DICOM files from the ICF store (which would serve as the data source
 for dataset clones); see :ref:`dl-access`.
-
-.. rubric:: Footnotes
-
-.. [1] To install software with pip, run a call such as the one below
-       in your favourite `virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_::
-
-         python -m pip install datalad-next

docs/source/user/datalad-requirements.rst

@@ -0,0 +1,35 @@
+.. _dl-requirements:
+
+DataLad requirements
+--------------------
+
+Accessing the ICF store contents and cloning datasets generated with
+the ICF tooling requires `DataLad`_ with `Datalad-Next`_ extension
+installed.  You can find instructions for installing DataLad on your
+operating system in the `DataLad Handbook`_.  `Datalad-Next`_ can be
+installed with `pip`_ [1]_.
+
+Generating DataLad datasets based on the DICOMS in the ICF store
+additionally requires the INM-ICF tools, which are packaged as a
+`Singularity`_ container; see :ref:`container`. The tools are not
+required for accessing already existing DataLad datasets.
+
+Obtaining data hosted in the ICF store requires access credentials for
+a given study, issued by the ICF. DataLad acts only as a client
+software. See :ref:`dl-credentials` for details.
+
+.. rubric:: Footnotes
+
+.. [1] To install software with pip, run a call such as the one below
+       in your favourite `virtual environment`_:
+
+       .. code-block:: bash
+
+          python -m pip install datalad-next
+
+.. _datalad: https://www.datalad.org/
+.. _datalad-next: https://docs.datalad.org/projects/next
+.. _datalad handbook: https://handbook.datalad.org/intro/installation.html
+.. _pip: https://pip.pypa.io/en/stable/
+.. _virtual environment: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/
+.. _singularity: https://docs.sylabs.io/guides/main/user-guide/

docs/source/user/index.rst

@@ -15,6 +15,7 @@ Please contact `ICF personnel`_ to get access and for any authentication-related
    :caption: Contents:
 
    browser
+   datalad-requirements
    datalad-credentials
    datalad-generate
    datalad-access