Docs updates (#4)

* Update rtd configuration
* Updated docs and readme

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "3.11"
     # You can also specify other tool versions:
     # nodejs: "19"
     # rust: "1.64"

README.md

@@ -1,3 +1,5 @@
 # SPIMquant
 
-Snakebids app for quantitative analysis of SPIM (lightsheet) brains
+[![Documentation Status](https://readthedocs.org/projects/spimquant/badge/?version=latest)](https://spimquant.readthedocs.io/en/latest/?badge=latest)
+
+Snakebids app for quantitative analysis of SPIM (lightsheet) brains. Documentation is linked above.

docs/conf.py

@@ -30,6 +30,7 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinxarg.ext",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/getting_started/installation.md

@@ -3,7 +3,7 @@
 Install from github with pip:
 
 ```bash
-pip install -e git+https://github.com/akhanf/spimquant#egg=spimquant
+pip install -e git+https://github.com/khanlab/spimquant#egg=spimquant
 ```
 
 Note: you can re-run this command to re-install with the latest version
@@ -13,79 +13,27 @@ Note: you can re-run this command to re-install with the latest version
 Do a dry-run first (`-n`) and simply print (`-p`) what would be run:
 
 ```bash
-spimquant /path/to/bids/dir /path/to/output/dir participant -np
+spimquant /path/to/bids/dir /path/to/output/dir participant -np --use-apptainer
 ```
 
 Run the app, using all cores::
 
 ```bash
-spimquant /path/to/bids/dir /path/to/output/dir participant --cores all
+spimquant /path/to/bids/dir /path/to/output/dir participant --cores all --use-apptainer
 ```
 
-If any workflow rules require containers, then run with the `--use-singularity` option.
 
 ## Generating a report
 
 After your processing is complete, you can use snakemake's `--report` feature to generate
 an HTML report. This report will include a graph of all the jobs run, with clickable nodes
 to inspect the shell command or python code used in each job, along with the config files and
-run times for each job. Workflows may also contain append images for quality assurance or to
-summarize outputs, by using the `report(...)` function on any snakemake output.
+run times for each job. 
 
 To generate a report, run:
 
 ```bash
 spimquant /path/to/bids/dir /path/to/output/dir participant --report
 ```
 
-## Compute Canada Instructions
 
-### Setting up a dev environment
-
-Here are some instructions to get your python environment set-up on graham to run spimquant:
-
-# Create a virtualenv and activate it:
-
-```bash
-cd $SCRATCH
-module load python/3
-virtualenv venv_spimquant
-source venv_spimquant/bin/activate
-```
-
-# Follow the steps above to install from github repository
-
-### Install job submission helpers
-
-Snakemake can submit jobs with SLURM, but you need to set-up a Snakemake profile to enable this. The Khan lab has a
-snakemake profile that is configured for graham but is customizable upon install, please see `cc-slurm <https://github.com/khanlab/cc-slurm>` for more info.
-
-If you don't need Snakemake to parallelize jobs across different nodes, you can make use of the simple job submission wrappers in `neuroglia-helpers <https://github.com/khanlab/neuroglia-helpers>`, e.g. `regularSubmit` or `regularInteractive` wrappers.
-
-These are used in the instructions below.
-
-### Running jobs on Compute Canada
-
-In an interactive job (for testing):
-
-```bash
-regularInteractive -n 8 spimquant bids_dir out_dir participant --participant_label 001 -j 8
-```
-
-Submitting a job (for larger cores, more subjects), still single job, but snakemake will parallelize over the 32 cores:
-
-```bash
-regularSubmit -j Fat spimquant bids_dir out_dir participant  -j 32
-```
-
-Scaling up to ~hundred subjects (needs cc-slurm snakemake profile installed), submits 1 16core job per subject:
-
-```bash
-spimquant bids_dir out_dir participant  --profile cc-slurm
-```
-
-Scaling up to even more subjects (uses group-components to bundle multiple subjects in each job), 1 32core job for N subjects (e.g. 10):
-
-```bash
-spimquant bids_dir out_dir participant  --profile cc-slurm --group-components subj=10
-```

docs/index.md

@@ -22,6 +22,5 @@ getting_started/installation
 :hidden:
 :maxdepth: 1
 
-usage/app_cli
-usage/snakemake_cli
+usage/cli
 ```

docs/requirements.txt

@@ -1,4 +1,5 @@
-docutils<0.18
-sphinx-argparse
-sphinx_rtd_theme
-snakebids==0.10.2
+sphinx-argparse==0.4.0
+sphinx-rtd-theme==2.0.0
+snakebids==0.13.1
+myst-parser==3.0.1
+.

docs/usage/cli.md

@@ -0,0 +1,26 @@
+## Core command-line interface
+
+The spimquant tool command-line interface is a composition of the core 
+(app-based) arguments and options, and the options related to Snakemake. 
+
+The core BIDS App arguments and app-specific options are listed below. 
+
+
+```{argparse}
+:ref: spimquant.run.get_parser
+:prog: spimquant
+```
+
+## Snakemake-based command-line interface
+
+Both core and Snakemake options are to be provided on the same command-line,  that 
+is, any Snakemake CLI option can be used when running the app.
+
+The Snakemake-based command-line options are detailed below. 
+
+```{argparse}
+:module: snakebids.snakemake_compat
+:func: get_argument_parser
+:prog: snakemake
+```
+