[MAINT] use sphinx argparse to automatically render the cli arguments doc

docs/source/conf.py

@@ -25,6 +25,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinxarg.ext",
 ]
 
 templates_path = ["_templates"]
@@ -35,7 +36,6 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
 
 # -- Options for myst_parser -------------------------------------------------
 myst_enable_extensions = ["colon_fence"]

docs/source/contributing.md

@@ -75,7 +75,7 @@ The workflow is the same as code contributions, with some minor differences.
 1. Install the `[doc]` dependencies.
 
 ```bash
-pip install -e .[doc]
+pip install -e '.[doc]'
 ```
 
 2. After making changes, build the docs locally:
@@ -104,7 +104,7 @@ This tells the development team that your pull request is a "work-in-progress",
 
 One your PR is ready a member of the development team will review your changes to confirm that they can be merged into the main codebase.
 
-## Making an release
+## Making a release
 
 Currently this project is not pushed to PyPi.
 We simply tag the version on the repository so users can reference the version of installation.

docs/source/usage.md

@@ -1,48 +1,17 @@
 # Usage Notes
 
-```bash
-usage: giga_connectome [-h] [-v] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-w WORK_DIR] [--atlas ATLAS]
-                       [--denoise-strategy DENOISE_STRATEGY] [--standardize {zscore,psc}] [--smoothing_fwhm SMOOTHING_FWHM] [--reindex-bids]
-                       [--bids-filter-file BIDS_FILTER_FILE]
-                       bids_dir output_dir {participant,group}
-
-Generate connectome based on denoising strategy for fmriprep processed dataset.
-
-positional arguments:
-  bids_dir              The directory with the input dataset (e.g. fMRIPrep derivative)formatted according to the BIDS standard.
-  output_dir            The directory where the output files should be stored.
-  {participant,group}   Level of the analysis that will be performed. Only group level is allowed as we need to generate a dataset inclusive brain mask.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
-                        The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include 'sub-'). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.
-  -w WORK_DIR, --work-dir WORK_DIR
-                        Path where intermediate results should be stored.
-  --atlas ATLAS         The choice of atlas for time series extraction. Default atlas choices are: 'Schaefer20187Networks, 'MIST', 'DiFuMo'. User can pass a path to a json file containing configuration for their own choice of atlas. The default is 'MIST'.
-  --denoise-strategy DENOISE_STRATEGY
-                        The choice of post-processing for denoising. The default choices are: 'simple', 'simple+gsr', 'scrubbing.2', 'scrubbing.2+gsr', 'scrubbing.5', 'scrubbing.5+gsr', 'acompcor50', 'icaaroma'. User can pass a path to a json file containing configuration for their own choice of denoising strategy. The defaultis 'simple'.
-  --standardize {zscore,psc}
-                        The choice of signal standardization. The choices are z score or percent signal change (psc). The default is 'zscore'.
-  --smoothing_fwhm SMOOTHING_FWHM
-                        Size of the full-width at half maximum in millimeters of the spatial smoothing to apply to the signal. The default is 5.0.
-  --reindex-bids        Reindex BIDS data set, even if layout has already been created.
-  --bids-filter-file BIDS_FILTER_FILE
-                        A JSON file describing custom BIDS input filters using PyBIDS.We use the same format as described in fMRIPrep documentation: https://fmriprep.org/en/latest/faq.html#how-do-i-select-only-certain-files-to-be-input-to-fmriprepHowever, the query filed should always be 'bold'
+## Command line interface
 
+```{eval-rst}
+.. argparse::
+   :prog: giga_connectome
+   :module: giga_connectome.run
+   :func: global_parser
 ```
 
-When performing `participant` level analysis, the output is a HDF5 file per participant that was passed to `--participant_label` or all subjects under `bids_dir`.
-The output file name is: `sub-<participant_id>_atlas-<atlas_name>_desc-<denoising_strategy>.h5`
-
-When performing `group` level analysis, the output is a HDF5 file per participant that was passed to `--participant_label` or all subjects under `bids_dir`.
-The output file name is: `atlas-<atlas_name>_desc-<denoising_strategy>.h5`
-The file will contain time series and connectomes of each subject, as well as group average connectomes.
-
 ## Writing configuration files
 
-All preset can be found in `giga_connectome/data`
+All preset can be found in [`giga_connectome/data`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data).
 
 ### Denoising strategy
 
@@ -62,13 +31,14 @@ In a `json` file, define the customised strategy in the following format:
 }
 ```
 
-See examples in `giga_connectome/data/denoise_strategy`.
+See examples in [`giga_connectome/data/denoise_strategy`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data/denoise_strategy).
 
 ### Atlas
 
 After the atlas files are organised according to the [TemplateFlow](https://www.templateflow.org/python-client/0.7.1/naming.html) convention.
 
 A minimal set up should look like this:
+
 ```
 my_atlas/
   └──tpl-MNI152NLin2009cAsym/  # template directory of a valid template name
@@ -96,4 +66,4 @@ In a `json` file, define the customised atlas. We will use the atlas above as an
 }
 ```
 
-See examples in `giga_connectome/data/atlas`.
+See examples in [`giga_connectome/data`](https://github.com/SIMEXP/giga_connectome/tree/main/giga_connectome/data).

giga_connectome/run.py

@@ -4,8 +4,7 @@
 from giga_connectome import __version__
 
 
-def main(argv=None):
-    """Entry point."""
+def global_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         formatter_class=argparse.RawTextHelpFormatter,
         description=(
@@ -105,6 +104,12 @@ def main(argv=None):
         "pipeline (option A). The default is False.",
         action="store_true",
     )
+    return parser
+
+
+def main(argv=None):
+    """Entry point."""
+    parser = global_parser()
 
     args = parser.parse_args(argv)
 

pyproject.toml

@@ -45,7 +45,8 @@ test = [
 docs = [
   "sphinx",
   "sphinx_rtd_theme",
-  "myst-parser"
+  "myst-parser",
+  "sphinx-argparse"
 ]
 # Aliases
 tests = ["giga_connectome[test]"]