From 5b76352beea59bdd35d20a9f66482f6f005aa881 Mon Sep 17 00:00:00 2001
From: Reinder Vos de Wael <reinder.vosdewael@childmind.org>
Date: Tue, 18 Jul 2023 15:44:36 -0400
Subject: [PATCH] improve documentation

---
 README.md                          | 23 ++++++++++++++---------
 src/ba_timeseries_gradients/cli.py | 17 +++++++++--------
 2 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 57df918..4184528 100644
--- a/README.md
+++ b/README.md
@@ -9,22 +9,27 @@ This is a command line interface (CLI) running BrainSpace on BIDS-compliant data
 
 ## Installation
 
-A PyPi installation will follow soon. Until then, the recommended approaches for installing ba-timeseries-gradients is through Docker. To build it, download the repository and run the following command from the repository root:
+The recommended approaches for installing ba-timeseries-gradients is through Docker or PyPi. To build it as a Docker image, download the repository and run the following command from the repository root:
 
+```bash
+docker build -t ba_timeseries_gradients .
 ```
-docker build -t ba-timeseries-gradients .
+
+To install through PyPi, run the following command:
+
+```bash
+pip install ba_timeseries_gradients
 ```
 
 ## Usage
 
-The basic usage of the ba-timeseries-gradients CLI is as follows:
+The basic usage of the ba_timeseries_gradients CLI is as follows, depending on whether you've installed through PyPi or Docker:
 
-```
-docker run ba-timeseries-gradients [OPTIONS] BIDS_DIR OUTPUT_DIR ANALYSIS_LEVEL
+```bash
+docker run --volume LOCAL_BIDS_DIR:BIDS_DIR --volume LOCAL_OUTPUT_DIR:OUTPUT_DIR ba_timeseries_gradients [OPTIONS] BIDS_DIR OUTPUT_DIR ANALYSIS_LEVEL
+ba_timeseries_gradients [OPTIONS] BIDS_DIR OUTPUT_DIR ANALYSIS_LEVEL
 ```
 
-For details on all the options, simply run:
+The `BIDS_DIR` is the path to the BIDS directory containing the dataset to be analyzed. The `OUTPUT_DIR` is the path to the directory where the output will be saved. The `ANALYSIS_LEVEL` is the level of analysis to be performed, which can currently only be `group`.
 
-```
-docker run ba-timeseries-gradients -h
-```
+For a complete list of options see `ba_timeseries_gradients -h`. It is highly recommended to include options to filter the dataset for specific files. See the BIDS arguments section in the help for more details.
diff --git a/src/ba_timeseries_gradients/cli.py b/src/ba_timeseries_gradients/cli.py
index d82956a..494aaca 100755
--- a/src/ba_timeseries_gradients/cli.py
+++ b/src/ba_timeseries_gradients/cli.py
@@ -56,6 +56,7 @@ def _get_parser() -> argparse.ArgumentParser:
         files are volumetric, they must be in NIFTI format, and a parcellation
         file must be provided.""",
         epilog="""Issues can be reported at: https://github.com/cmi-dair/ba_timeseries_gradients.""",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
 
     mandatory_group = parser.add_argument_group("Mandatory arguments")
@@ -85,7 +86,7 @@ def _get_parser() -> argparse.ArgumentParser:
         type=str,
         action="append",
         dest="sub",
-        help="The subject to include for finding BIDS files. Defaults to all subjects.",
+        help="The subject to include for finding BIDS files.",
     )
     bids_group.add_argument(
         "--session",
@@ -94,14 +95,14 @@ def _get_parser() -> argparse.ArgumentParser:
         type=int,
         action="append",
         dest="ses",
-        help="The session to include for finding BIDS files. Defaults to all sessions.",
+        help="The session to include for finding BIDS files.",
     )
     bids_group.add_argument(
         "--suffix",
         required=False,
         default="bold",
         type=str,
-        help="Suffix to use for finding BIDS files. Defaults to 'bold'.",
+        help="Suffix to use for finding BIDS files.",
     )
     bids_group.add_argument(
         "--run",
@@ -109,7 +110,7 @@ def _get_parser() -> argparse.ArgumentParser:
         default=None,
         type=int,
         action="append",
-        help="The runs to include, may be supplied multiple times. Defaults to all runs.",
+        help="The runs to include, may be supplied multiple times.",
     )
     bids_group.add_argument(
         "--task",
@@ -117,7 +118,7 @@ def _get_parser() -> argparse.ArgumentParser:
         default=None,
         type=str,
         action="append",
-        help="The tasks to include, may be supplied multiple times. Defaults to all tasks.",
+        help="The tasks to include, may be supplied multiple times.",
     )
     bids_group.add_argument(
         "--extension",
@@ -125,7 +126,7 @@ def _get_parser() -> argparse.ArgumentParser:
         default=".nii.gz",
         type=str,
         dest="ext",
-        help="Extension to use for finding BIDS files. Defaults to '.nii.gz'.",
+        help="Extension to use for finding BIDS files.",
     )
     bids_group.add_argument(
         "--datatype",
@@ -179,14 +180,14 @@ def _get_parser() -> argparse.ArgumentParser:
         required=False,
         default=logging.INFO,
         type=int,
-        help="Verbosity level. Must be one of: 10 (DEBUG), 20 (INFO), 30 (WARNING), 40 (ERROR), 50 (CRITICAL). Defaults to 10.",
+        help="Verbosity level. Must be one of: 10 (DEBUG), 20 (INFO), 30 (WARNING), 40 (ERROR), 50 (CRITICAL).",
     )
     other_group.add_argument(
         "--output_format",
         required=False,
         default="hdf5",
         type=str,
-        help="Output format. Must be one of: 'hdf5', or 'json'. Defaults to 'hdf5'.",
+        help="Output format. Must be one of: 'hdf5', or 'json'.",
     )
     return parser