📝 Add user docs re: C-PAC versions

Author: shnizzedy

docs/_sources/conf.py

@@ -573,14 +573,24 @@ def _unireplace(release_note, unireplace):
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
 
+rst_prolog = """
+
+.. |version as code| replace:: ``{version}``
+
+""".format(
+    version=f'v{version}' if not version.endswith('dev') else 'nightly'
+)
+
 rst_epilog = """
 
+
 .. |Versions| replace:: {versions}
 
 """.format(
     versions=', '.join(gh_tags[:5])
 ) if len(gh_tags) >= 5 else ""
 
+
 def setup(app):
     from CPAC.utils.monitoring import custom_logging
 

docs/_sources/user/cpac.rst

@@ -24,7 +24,7 @@ or
 
     cpac upgrade
 
-When downloading/upgrading, the ``--platform``, ``--image``, and ``--tag`` let you specify platform (Docker or Singularity), image (Docker image name or URL to image in repository), and tag (version tag, currently only for Docker repositories), respectively.
+When downloading/upgrading, the ``--platform``, ``--image``, and ``--tag`` let you specify platform (Docker or Singularity), image (Docker image name or URL to image in repository), and tag (:doc:`version tag </user/versions>`), respectively.
 
 For example, a development Docker image can be downloaded with
 
@@ -70,6 +70,8 @@ Usage
 
 You can also specify a container image with an ``--image`` argument, passing an image name (e.g., ``fcpindi/c-pac``) for a Docker image or a filepath (e.g. ``~/singularity_images/C-PAC.sif``) for a Singularity image. You can also specify a ``--tag`` (e.g., ``latest`` or ``nightly``).
 
+   .. seealso:: :doc:`/user/versions`
+
 You can also provide a link to an AWS S3 bucket containing a BIDS directory as the data source:
 
 .. code-block:: console
@@ -115,7 +117,3 @@ Note that any of the optional arguments above will over-ride any pipeline settin
 * The ``participant_label`` and ``participant_ndx`` arguments allow the user to specify which of the many datasets should be processed, which is useful when parallelizing the run of multiple participants.
 
 * If you want to pass runtime options to your container plaform (Docker or Singularity), you can pass them with ``-o`` or ``--container_options``.
-
-.. rubric:: Footnotes
-
-.. [*] The version restrictions for Singularity are specific to cpac the convenience wrapper. C-PAC itself should :doc:`run on Singularity <singularity>` 2 or 3.

docs/_sources/user/docker.rst

@@ -15,6 +15,8 @@ To start, first pull the image from Docker Hub:
 
 Once this is complete, you can use the ``fcpindi/c-pac:latest`` image tag to invoke runs. The full C-PAC Docker image usage options are shown here, with some specific use cases.
 
+   .. seealso:: :doc:`/user/versions`
+
 As a quick example, in order to run the C-PAC Docker container in participant mode, for one participant, using a BIDS dataset stored on your machine or server, and using the Docker image's default pipeline configuration (broken into multiple lines for visual clarity):
 
 .. code-block:: console

docs/_sources/user/index.rst

@@ -113,3 +113,8 @@ User Guide Index
    10. Troubleshoot <help>
    11. Release Notes <rnotes>
    12. Appendix <appendix>
+
+.. toctree::
+   :hidden:
+
+   versions

docs/_sources/user/versions.rst

@@ -0,0 +1,29 @@
+C-PAC versions
+==============
+
+See :doc:`Release Notes </user/rnotes>` for information about specific versions of C-PAC. The Docker Hub tags are like ``fcpindi/c-pac:release-${VERSION}${VARIANT}`` where ``${VERSION}`` is either a specific semantic version prefixed with a ``v`` or ``latest`` or ``nightly``, like |example version|
+
+Variants
+^^^^^^^^
+
+Primary image
+-------------
+
+Non-variant, primary image (no ``${VARIANT}`` or an empty string, e.g. |example version|)
+
+Lite variant
+------------
+
+``-lite``, primary image without FreeSurfer for a smaller image for runs that don't need FreeSurfer (e.g., |example version|\ ``-lite``)
+
+ABCD-HCP variant
+----------------
+
+``-ABCD-HCP``, image with software dependencies version-matched to `ABCD-HCP BIDS fMRI Pipeline <https://github.com/DCAN-Labs/abcd-hcp-pipeline/blob/e480a8f99534f1b05f37bf44c64827384b69b383/Dockerfile>`_ (e.g., |example version|\ ``-ABCD-HCP``)
+
+fMRIPrep-LTS variant
+--------------------
+
+``-fMRIPrep-LTS``, image with software dependencies version-matched to `fMRIPrep LTS <https://reproducibility.stanford.edu/fmriprep-lts#long-term-support-lts>`_ (e.g., |example version|\ ``-fMRIPrep-LTS``)
+
+.. |example version| replace:: ``release-``\ |version as code|