Update documentation (#1328)

Author: tsalo

README.rst

@@ -42,19 +42,19 @@ for open-source software distribution.
 About
 *****
 
-XCP-D paves the final section of the reproducible and scalable route from the MRI scanner to
+*XCP-D* paves the final section of the reproducible and scalable route from the MRI scanner to
 functional connectivity data in the hands of neuroscientists.
-We developed XCP-D to extend the BIDS and NiPrep apparatus to the point where data is most
+We developed *XCP-D* to extend the BIDS and NiPrep apparatus to the point where data is most
 commonly consumed and analyzed by neuroscientists studying functional connectivity.
-Thus, with the development of XCP-D, data can be automatically preprocessed and analyzed in BIDS
+Thus, with the development of *XCP-D*, data can be automatically preprocessed and analyzed in BIDS
 format, using NiPrep-style containerized code, all the way from the scanner to functional
 connectivity matrices.
 
-XCP-D picks up right where `fMRIprep <https://fmriprep.org>`_ ends, directly consuming the outputs
+*XCP-D* picks up right where `fMRIprep <https://fmriprep.org>`_ ends, directly consuming the outputs
 of fMRIPrep.
-XCP-D leverages the BIDS and NiPreps frameworks to automatically generate denoised BOLD images,
+*XCP-D* leverages the BIDS and NiPreps frameworks to automatically generate denoised BOLD images,
 parcellated time series, functional connectivity matrices, and quality assessment reports.
-XCP-D can also process outputs from: `NiBabies <https://nibabies.readthedocs.io>`_,
+*XCP-D* can also process outputs from: `NiBabies <https://nibabies.readthedocs.io>`_,
 `ABCD-BIDS <https://github.com/DCAN-Labs/abcd-hcp-pipeline>`_,
 `Minimally preprocessed HCP <https://www.humanconnectome.org/study/hcp-lifespan-development/\
 data-releases>`_,
@@ -67,37 +67,37 @@ and `UK Biobank <https://doi.org/10.1016/j.neuroimage.2017.10.034>`_ data.
 See the `documentation <https://xcp-d.readthedocs.io/en/latest/>`_ for more details.
 
 
-Why you should use XCP-D
-````````````````````````
+Why you should use *XCP-D*
+``````````````````````````
 
-XCP-D produces the following commonly-used outputs: matrices, parcellated time series,
+*XCP-D* produces the following commonly-used outputs: matrices, parcellated time series,
 dense time series, and additional QC measures.
 
-XCP-D is designed for resting-state or pseudo-resting-state functional connectivity analyses.
-XCP-D derivatives may be useful for seed-to-voxel and ROI-to-ROI functional connectivity analyses,
+*XCP-D* is designed for resting-state or pseudo-resting-state functional connectivity analyses.
+*XCP-D* derivatives may be useful for seed-to-voxel and ROI-to-ROI functional connectivity analyses,
 as well as decomposition-based methods, such as ICA or NMF.
 
 
-When you should not use XCP-D
-`````````````````````````````
+When you should not use *XCP-D*
+```````````````````````````````
 
-XCP-D is not designed as a general-purpose postprocessing pipeline.
+*XCP-D* is not designed as a general-purpose postprocessing pipeline.
 It is really only appropriate for certain analyses,
 and other postprocessing/analysis tools are better suited for many types of data/analysis.
 
-XCP-D derivatives are not particularly useful for task-dependent functional connectivity analyses,
+*XCP-D* derivatives are not particularly useful for task-dependent functional connectivity analyses,
 such as psychophysiological interactions (PPIs) or beta series analyses.
 It is also not suitable for general task-based analyses, such as standard task GLMs,
 as we recommend including nuisance regressors in the GLM step,
 rather than denoising data prior to the GLM.
 
 
-************
-Citing XCP-D
-************
+**************
+Citing *XCP-D*
+**************
 
-If you use XCP-D in your research, please use the boilerplate generated by the workflow.
-If you need an immediate citations, please cite the following preprint:
+If you use *XCP-D* in your research, please use the boilerplate generated by the workflow.
+If you need an immediate citation, please cite the following paper:
 
    Mehta, K., Salo, T., Madison, T. J., Adebimpe, A., Bassett, D. S., Bertolero, M., ... & Satterthwaite, T. D.
    (2024).

docs/contributing.rst

@@ -4,7 +4,7 @@
 Contributing to *XCP-D*
 #######################
 
-This guide describes the organization and preferred coding style for XCP-D,
+This guide describes the organization and preferred coding style for *XCP-D*,
 for prospective code contributors.
 
 .. important::
@@ -57,7 +57,7 @@ but the main ones are ``black`` and ``isort``.
 
 .. tip::
 
-   Please run ``isort`` and ``black`` on the ``XCP-D`` codebase before opening a pull request.
+   Please run ``isort`` and ``black`` on the *XCP-D* codebase before opening a pull request.
 
    Also run ``flake8`` to check for any additional style issues.
 
@@ -129,9 +129,9 @@ Here is an example of a basic workflow, written in the preferred style for *XCP-
       return workflow
 
 
-*************************************************
-Contributing to XCP-D without adding dependencies
-*************************************************
+***************************************************
+Contributing to *XCP-D* without adding dependencies
+***************************************************
 
 In the most common case, you will want to modify *XCP-D*'s Python code without adding any
 dependencies (Python or not) to the Docker image.
@@ -144,15 +144,15 @@ image yourself.
 
       docker pull pennlinc/xcp_d:unstable
 
-2. Fork the XCP-D repository to your GitHub account.
+2. Fork the *XCP-D* repository to your GitHub account.
    For more information on contributing via the fork-and-branch approach,
    see `GitHub's contributing guide
    <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_.
 
 3. Clone your forked repository to your local machine.
 
 4. Create a branch to work on.
-   **Make sure your branch is up to date with XCP-D's ``main`` branch before making any
+   **Make sure your branch is up to date with *XCP-D*'s ``main`` branch before making any
    changes!**
 
 5. Make changes to the codebase that you want to try out.
@@ -175,26 +175,44 @@ image yourself.
 
 7. Push your changes to GitHub.
 
-8. Open a pull request to PennLINC/XCP-D's ``main`` branch.
+8. Open a pull request to ``pennlinc/xcp_d``'s ``main`` branch.
    Please follow `NiPreps contributing guidelines <https://www.nipreps.org/community/>`_
    when preparing a pull request.
 
 
-Running tests
-=============
+Running tests locally
+=====================
 
 While CircleCI will automatically run *XCP-D*'s tests for any open PRs,
 we strongly recommend running at least some tests locally, to make sure your proposed changes work.
 
 *XCP-D* has a file, ``xcp_d/tests/run_local_tests.py``, that builds Docker ``run`` commands to
-run selected tests.
+to automatically mount the local clone into ``pennlinc/xcp_d:unstable`` and run tests with
+``pytest``.
+The script will also download any required test data from Box.
 Please use that script to run some tests locally before opening your PR.
 
+To run the tests, navigate to the tests folder and run ``run_local_tests.py``::
+
+    $ cd /path/to/xcp_d/xcp_d/tests
+    $ python run_local_tests.py
+
+You can select individual tests to run by using the ``-m`` (to select markers) or
+``-k`` (the select tests by name) flags::
+
+    $ python run_local_tests.py -m "dsdti_fmap"
+    $ python run_local_tests.py -k "test_some_name"
+
 If all tests pass, this is a strong indication that your proposed changes do not introduce bugs.
 However, we strongly recommend reviewing the output files- especially the HTML reports-
 from the integration tests to see how your proposed changes affect the primary outputs from
 *XCP-D*.
 
+.. warning::
+
+    Please note that the integration tests in *XCP-D* are computationally intensive
+    and may take a long time to run, so be prepared for that before running them on a laptop.
+
 
 ********************************
 Adding or modifying dependencies
@@ -220,9 +238,9 @@ and rebuild the *XCP-D* Docker image locally to test out your change.
 Once your change is working, you can open a pull request to the *XCP-D* repo.
 
 
-*****************
-Maintaining XCP-D
-*****************
+*******************
+Maintaining *XCP-D*
+*******************
 
 
 Making a Release
@@ -239,7 +257,7 @@ To make an *XCP-D* release, complete the following steps:
       (e.g., ``1.0.0``).
    #. For pre-releases, select the "This is a pre-release" option.
    #. Select the "Generate release notes" button.
-      This will create most of the necessary release notes based on XCP-D's config file.
+      This will create most of the necessary release notes based on *XCP-D*'s config file.
    #. At the top of the release notes, add some information summarizing the release.
 
 3. Once the release notes have been completed, open a new PR with the following changes:

docs/installation.rst

@@ -26,18 +26,18 @@ steps necessary for execution.
 
 Docker Installation
 ===================
-For every new version of *xcp_d* that is released, a corresponding Docker image is generated.
+For every new version of *XCP-D* that is released, a corresponding Docker image is generated.
 
-In order to run *xcp_d* via Docker images, the Docker Engine must be installed.
+In order to run *XCP-D* via Docker images, the Docker Engine must be installed.
 
-If you have used *xcp_d* via Docker in the past, you might need to pull down a more recent version
+If you have used *XCP-D* via Docker in the past, you might need to pull down a more recent version
 of the image: ::
 
     $ docker pull pennlinc/xcp_d:<latest-version>
 
 The image can also be found here: https://hub.docker.com/r/pennlinc/xcp_d
 
-*xcp_d* can be run interacting directly with the Docker Engine via the `docker run` command,
+*XCP-D* can be run interacting directly with the Docker Engine via the `docker run` command,
 or through a lightweight wrapper that was created for convenience.
 
 
@@ -65,11 +65,11 @@ Manually Prepared Environment (Python 3.10)
    This method is not recommended! Please use container alternatives
    in :ref:`run_docker`, and :ref:`run_apptainer`.
 
-XCP-D requires some `External Dependencies`_.
+*XCP-D* requires some `External Dependencies`_.
 These tools must be installed and their binaries available in the system's ``$PATH``.
 
 On a functional Python 3.10 environment with ``pip`` installed,
-XCP-D can be installed using the habitual command
+*XCP-D* can be installed using the habitual command
 ::
 
     $ pip install git+https://github.com/pennlinc/xcp_d.git
@@ -86,7 +86,7 @@ External Dependencies
 
 *XCP-D* is written using Python 3.10, is based on nipype_,
 and requires some other neuroimaging software tools that are not handled by the Python's packaging
-system (PyPi) used to deploy the XCP-D package:
+system (PyPi) used to deploy the *XCP-D* package:
 
 -  ANTs_ (version 2.2.0 - or higher)
 -  AFNI_ (version Debian-16.2.07)

docs/outputs.rst

@@ -74,7 +74,7 @@ the HCP thalamic atlas :footcite:p:`najdenovska2018vivo`,
 and the amygdala and hippocampus parcels from the HCP CIFTI subcortical parcellation
 :footcite:p:`glasser2013minimal`.
 The 4S atlas is used in the same manner across three PennLINC BIDS Apps:
-XCP-D, QSIPrep_, and ASLPrep_, to produce synchronized outputs across modalities.
+*XCP-D*, QSIPrep_, and ASLPrep_, to produce synchronized outputs across modalities.
 For more information about the 4S atlas, please see https://github.com/PennLINC/AtlasPack.
 
 .. tip::