improve doc cli

Author: Remi-Gau

cohort_creator/_cli.py

@@ -9,6 +9,7 @@
 
 import pandas as pd
 from datalad import api
+from rich_argparse import RichHelpFormatter
 
 from cohort_creator._parsers import global_parser
 from cohort_creator._utils import get_bids_filter
@@ -56,7 +57,7 @@ def create_yoda(output_dir: Path) -> None:
 
 def cli(argv: Sequence[str] = sys.argv) -> None:
     """Entry point."""
-    parser = global_parser()
+    parser = global_parser(formatter_class=RichHelpFormatter)
 
     args, _ = parser.parse_known_args(argv[1:])
 

cohort_creator/_parsers.py

@@ -2,24 +2,23 @@
 from __future__ import annotations
 
 from argparse import ArgumentParser
-
-from rich_argparse import RichHelpFormatter
+from argparse import HelpFormatter
 
 from ._version import __version__
 
 DOC_URL = "https://cohort-creator.readthedocs.io/en/latest/"
 FAQ_URL = f"{DOC_URL}faq.html"
 
 
-def base_parser() -> ArgumentParser:
+def base_parser(formatter_class: type[HelpFormatter] = HelpFormatter) -> ArgumentParser:
     parser = ArgumentParser(
         prog="cohort_creator",
         description="Creates a cohort by grabbing specific subjects from opennneuro datasets.",
         epilog=f"""
         For a more readable version of this help section,
         see the `online doc <{DOC_URL}>`_.
         """,
-        formatter_class=RichHelpFormatter,
+        formatter_class=formatter_class,
     )
     parser.add_argument(
         "-v",
@@ -128,8 +127,8 @@ def add_specialized_args(parser: ArgumentParser) -> ArgumentParser:
     return parser
 
 
-def global_parser() -> ArgumentParser:
-    parser = base_parser()
+def global_parser(formatter_class: type[HelpFormatter] = HelpFormatter) -> ArgumentParser:
+    parser = base_parser(formatter_class=formatter_class)
     subparsers = parser.add_subparsers(
         dest="command",
         help="Choose a subcommand",
@@ -138,63 +137,19 @@ def global_parser() -> ArgumentParser:
 
     install_parser = subparsers.add_parser(
         "install",
-        help="""
-        Install several openneuro datasets.
-
-        Example:
-
-        .. code-block:: bash
-
-            cohort_creator install \\
-                --dataset_listing inputs/dataset-results.tsv \\
-                --participant_listing inputs/participant-results.tsv \\
-                --output_dir outputs \\
-                --dataset_types raw mriqc fmriprep \\
-                --verbosity 3
-
-        If no ``--participant_listing`` is provided,
-        a ``participants.tsv`` file will be generated
-        in ``output_dir/code`` that contains all participants
-        for all datasets in ``dataset_listing``.
-
-        Datasets listing can be passed directly as a list of datasets:
-
-        .. code-block:: bash
-
-            cohort_creator install \\
-                --dataset_listing ds000001 ds000002 \\
-                --output_dir outputs \\
-                --dataset_types raw mriqc fmriprep \\
-                --verbosity 3
-        """,
+        help="Install several openneuro datasets.",
         formatter_class=parser.formatter_class,
     )
     install_parser = add_common_arguments(install_parser)
     install_parser.add_argument(
         "--generate_participant_listing",
         action="store_true",
-        help="Skips rerunning mriqc on the subset of participants.",
+        help="Generate a participant_listing.tsv in the output_dir.",
     )
 
     get_parser = subparsers.add_parser(
         "get",
-        help="""
-        Get specified data for a cohort of subjects.
-
-        Example:
-
-        .. code-block:: bash
-
-            cohort_creator get \\
-                --dataset_listing inputs/dataset-results.tsv \\
-                --participant_listing inputs/participant-results.tsv \\
-                --output_dir outputs \\
-                --dataset_types raw mriqc fmriprep \\
-                --datatype anat func \\
-                --space T1w MNI152NLin2009cAsym \\
-                --jobs 6 \\
-                --verbosity 3
-        """,
+        help="Get specified data for a cohort of subjects.",
         formatter_class=parser.formatter_class,
     )
     get_parser = add_common_arguments(get_parser)
@@ -212,22 +167,7 @@ def global_parser() -> ArgumentParser:
 
     copy_parser = subparsers.add_parser(
         "copy",
-        help="""
-        Copy cohort of subjects into separate directory.
-
-        Example:
-
-        .. code-block:: bash
-
-            cohort_creator copy \\
-                --dataset_listing inputs/dataset-results.tsv \\
-                --participant_listing inputs/participant-results.tsv \\
-                --output_dir outputs \\
-                --dataset_types raw mriqc fmriprep \\
-                --datatype anat func \\
-                --space T1w MNI152NLin2009cAsym \\
-                --verbosity 3
-        """,
+        help="Copy cohort of subjects into separate directory.",
         formatter_class=parser.formatter_class,
     )
     copy_parser = add_common_arguments(copy_parser)
@@ -240,22 +180,7 @@ def global_parser() -> ArgumentParser:
 
     all_parser = subparsers.add_parser(
         "all",
-        help="""
-        Install, get, and copy cohort of subjects.
-
-        Example:
-
-        .. code-block:: bash
-
-            cohort_creator all \\
-                --dataset_listing inputs/dataset-results.tsv \\
-                --participant_listing inputs/participant-results.tsv \\
-                --output_dir outputs \\
-                --dataset_types raw mriqc fmriprep \\
-                --datatype anat func \\
-                --space T1w MNI152NLin2009cAsym \\
-                --verbosity 3
-        """,
+        help="Install, get, and copy cohort of subjects.",
         formatter_class=parser.formatter_class,
     )
     all_parser = add_common_arguments(all_parser)

docs/source/usage_notes.rst

@@ -9,3 +9,78 @@ Command-Line Arguments
    :prog: cohort_creator
    :module: cohort_creator._parsers
    :func: global_parser
+
+
+Examples
+--------
+
+install
+^^^^^^^
+
+.. code-block:: bash
+
+   cohort_creator install \
+         --dataset_listing inputs/dataset-results.tsv \
+         --participant_listing inputs/participant-results.tsv \
+         --output_dir outputs \
+         --dataset_types raw mriqc fmriprep \
+         --verbosity 3
+
+If no ``--participant_listing`` is provided,
+a ``participants.tsv`` file will be generated
+in ``output_dir/code`` that contains all participants
+for all datasets in ``dataset_listing``.
+
+Datasets listing can be passed directly as a list of datasets:
+
+.. code-block:: bash
+
+   cohort_creator install \
+         --dataset_listing ds000001 ds000002 \
+         --output_dir outputs \
+         --dataset_types raw mriqc fmriprep \
+         --verbosity 3
+
+get
+^^^
+
+.. code-block:: bash
+
+   cohort_creator get \
+         --dataset_listing inputs/dataset-results.tsv \
+         --participant_listing inputs/participant-results.tsv \
+         --output_dir outputs \
+         --dataset_types raw mriqc fmriprep \
+         --datatype anat func \
+         --space T1w MNI152NLin2009cAsym \
+         --jobs 6 \
+         --verbosity 3
+
+
+copy
+^^^^
+
+.. code-block:: bash
+
+   cohort_creator copy \
+         --dataset_listing inputs/dataset-results.tsv \
+         --participant_listing inputs/participant-results.tsv \
+         --output_dir outputs \
+         --dataset_types raw mriqc fmriprep \
+         --datatype anat func \
+         --space T1w MNI152NLin2009cAsym \
+         --verbosity 3
+
+all
+^^^
+
+.. code-block:: bash
+
+   cohort_creator all \
+         --dataset_listing inputs/dataset-results.tsv \
+         --participant_listing inputs/participant-results.tsv \
+         --output_dir outputs \
+         --dataset_types raw mriqc fmriprep \
+         --datatype anat func \
+         --space T1w MNI152NLin2009cAsym \
+         --verbosity 3