refactor!: Merge pull request #47 from brown-bnc/feat/add-documentation

BREAKING CHANGE: Changes the CLI to use typer, adds MkDocs, pre-commit hooks and Github Actions

.github/workflows/dev-docs.yml

@@ -0,0 +1,55 @@
+name: dev-docs 
+on:
+  push:
+    branches-ignore:
+      - master
+jobs: 
+  build: 
+    name: Build and Deploy Documentation 
+    runs-on: ubuntu-latest 
+    steps: 
+      - name: Checkout Master 
+        uses: actions/checkout@v2 
+      - name: Set up Python 3.7 
+        uses: actions/setup-python@v2 
+        with: 
+          python-version: '3.7.5' 
+      - name: Install dependencies 
+        run: | 
+          python -m pip install --upgrade pip 
+          pip install .
+          pip install mkdocs mkdocs-material mkdocstrings mkdocs-versioning
+          pip install typer-cli
+      - name: Set up mkdocs config
+        run: | 
+          export VERSION=dev
+          echo "Making docs for version $VERSION"
+          (envsubst '${VERSION}' < mkdocs-template.yml) > mkdocs.yml
+      - name: Generate CLI docs and copy CHANGELOG   
+        run: |
+          typer xnat_tools/xnat2bids.py utils docs --name xnat2bids --output docs/xnat2bids.md
+          typer xnat_tools/dicom_export.py utils docs --name xnat-dicom-export --output docs/dicom_export.md
+          typer xnat_tools/run_heudiconv.py utils docs --name xnat-heudiconv --output docs/run_heudiconv.md
+          typer xnat_tools/bids_postprocess.py utils docs --name bids-postprocess --output docs/bids_postprocess.md
+          cp CHANGELOG.md docs/changelog.md
+      - name: Push to remote
+        run: |
+          echo "Test push commit to the remote in the workflow" >> test.txt
+
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add -A
+          git commit -m "docs: Update CLI and CHANGELOG.md"
+          git push
+      - name: Sync 
+        run: |
+          git pull
+          mkdir site
+          mkdocs-versioning sync
+          rm -rf ./site/dev/
+          rm -rf ./site/.git/
+      - name: Build
+        run: mkdocs build
+      - name: Deploy
+        run: mkdocs-versioning -v deploy

.github/workflows/pre-commit.yml

@@ -0,0 +1,11 @@
+name: pre-commit
+
+on: [push]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+    - uses: pre-commit/[email protected]

.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: publish 
+on:
+  push:
+    branches:
+      - master
+jobs: 
+  bump_version:
+    runs-on: ubuntu-latest
+    name: 'Bump version and create changelog with commitizen'
+    steps:
+    - name: Check out
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - name: Create bump and changelog
+      uses: commitizen-tools/[email protected]
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+  docs:  
+    name: Build and Deploy Documentation 
+    runs-on: ubuntu-latest 
+    depends-on: bump_version
+    steps: 
+      - name: Checkout Master 
+        uses: actions/checkout@v2 
+      - name: Set up Python 3.7 
+        uses: actions/setup-python@v2 
+        with: 
+          python-version: '3.7.5' 
+      - name: Install dependencies 
+        run: | 
+          python -m pip install --upgrade pip 
+          pip install .
+          pip install mkdocs mkdocs-material mkdocstrings mkdocs-versioning
+      - name: Set up mkdocs config 
+        run: |
+          export VERSION=$(cat pyproject.toml | grep version | head -1 | awk -F: '{ print $1 }'| sed 's/[\",]//g'| tr -d 'version = ')
+          echo "Making docs for version $VERSION"
+          (envsubst 'v${VERSION}' < mkdocs-template.yml) > mkdocs.yml
+      - name: Sync 
+        run: | 
+          git pull
+          mkdir site
+          mkdocs-versioning sync
+          rm -rf ./site/.git/
+      - name: Build
+        run: mkdocs build
+      - name: Deploy
+        run: mkdocs-versioning -v deploy

.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: tests 
+on: [push]
+jobs: 
+  test: 
+    name: Run unit tests 
+    runs-on: ubuntu-latest 
+    steps: 
+      - name: Checkout Master 
+        uses: actions/checkout@v2 
+      - name: Set up Python 3.7 
+        uses: actions/setup-python@v2 
+        with: 
+          python-version: '3.7.5' 
+      - name: Install dependencies 
+        run: | 
+          python -m pip install --upgrade pip 
+          pip install .
+          pip install pytest python-dotenv responses
+      - name: Test 
+        run: pytest -k unit

.gitignore

@@ -107,6 +107,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+mkdocs.yml
 
 # mypy
 .mypy_cache/

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+    - repo: https://github.com/timothycrosley/isort
+      rev: 5.0.4
+      hooks:
+        - id: isort
+    - repo: https://github.com/ambv/black
+      rev: stable
+      hooks:
+        - id: black
+    - repo: https://gitlab.com/pycqa/flake8
+      rev: 3.8.3
+      hooks:
+        - id: flake8
+          args:
+          - "--max-line-length=89"
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: "v0.790"  # 2020.10.21
+      hooks:
+        - id: mypy
+default_language_version:
+    python: python3

README.md

@@ -1,152 +1,7 @@
 # XNAT Tools
 
-XNAT tools maintained by the Behavioral Neuroimaging Center for the Brown University MRI users. In this README we summarize
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/brown-bnc/xnat-tools)](https://github.com/brown-bnc/xnat-tools/releases/latest/) 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://brown-bnc.github.io/xnat-tools/)
+![tests](https://github.com/brown-bnc/xnat-tools/workflows/tests/badge.svg)
 
-1. [Installation](#Installatio)
-2. [XNAT2BIDS](#XNAT2BIDS)
-
-Additional instructions for the Brown University Community is available on the [BNC User Manual](docs.ccv.brown.edu/)
-
-## Installation
-
-### Using Docker
-
-```
-docker pull docker pull brownbnc/xnat_tools:<version>
-```
-
-_Version:_
-
-- `latest`: Is the build of master
-- `vX.X.X`: Latest tagged stable release
-
-You can confirm the tags [here](https://hub.docker.com/repository/docker/brownbnc/xnat_tools/tags?page=1)
-
-### Python
-
-### Prerequisites:
-
-We first need to install the dcm2niix . This is a dependency of Heudiconv, that doesn't get installed by Heudiconv itself
-
-```
-brew install dcm2niix
-```
-
-### Poetry
-
-This package is developed using [Poetry](https://python-poetry.org). If you are familiar with Poetry, you can add it to your project via
-
-```
-poetry add git+https://github.com/brown-bnc/xnat-tools.git
-```
-
-or for a tagged release
-
-```
-poetry add git+https://github.com/brown-bnc/[email protected]
-```
-
-You can also install xnat_tools using the python package manager of your choice. For instance:
-
-#### PIP
-
-- A Tagged Release
-
-```
-pip install git+https://github.com/brown-bnc/[email protected]
-```
-
-- Development (Master branch)
-
-```
-pip install git+https://github.com/brown-bnc/xnat-tools.git
-```
-
-#### PIPX
-
-If you are using this package in a stand-alone fashion, and you don't want to use Docker, we recommend using pipx. Please check their [installation instructions](https://github.com/pipxproject/pipx).
-
-Once pipx is installed you install as follows:
-
-A Tagged Release
-
-```
-pipx install git+https://github.com/brown-bnc/[email protected]
-```
-
-Development (Master branch)
-
-```
-pipx install git+https://github.com/brown-bnc/xnat-tools.git
-```
-
-## XNAT2BIDS
-
-In order to export data from XNAT and convert it in one step you can use the `xnat2bids` script part of this package.
-
-After installation, the console script `xnat2bids` is available in your system. You can invoke it from the terminal as follows:
-
-```
-xnat_user=<user>
-session=<xnat_accession_number>
-bids_root_dir="~/data/bids-export"
-
-xnat2bids --user ${xnat_user}  --session ${session} \
---bids_root_dir ${bids_root_dir}
-```
-
-### Understanding the inputs
-
-Familiarize yourself with the inputs to xnat2bids
-For a full list of the inputs, you can run:
-
-```
- xnat2bids --help
-```
-
-Some key optional inputs to be aware of:
-
-- `--bidsmap_file`: `xnat2bids` can take a json file with a dictionary of sequence names to correct/change. For instance you can pass `--bidsmap_file ./my_bidsmap.json`. The bidsmaps directory in this repository has examples of bidsmaps file
-- `--seqlist`: If you only want to export some sequences from XNAT, you can pass the list (use order in your XNAT). e.g., `--seqlist 1 2 3 4 5 7 8 9`
-- `--cleanup`: At the end on the process, the source data is avaialable in two directories `root_dir/xnat-export` and `root_dir/bids/sourcedata`. Passing the `--cleanup` flag removes `root_dir/xnat-export`
-
-### Understanding the process
-
-`xnat2bids` performs two main steps:
-
-1. Export to a [Heudiconv](https://github.com/nipy/heudiconv) friendly directory structure. We follow the structure suggested by [the ReproIn guide](https://github.com/ReproNim/reproin), enabling us to use their [heuristic file](https://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py).This step is encapsulated in `xnat_tools/dicom_export.py`
-
-2. We run Heudiconv using ReproIn heuristic. This step is encapsulated in `xnat_tools/run_heudiconv.py`
-
-If you'd like to run those steps separatly, you can do
-
-```
-xnat-dicom-export --user ${xnat_user}  \
---session ${session}                   \
---bids_root_dir ${bids_root_dir}
-```
-
-Followed by:
-
-```
-xnat-heudiconv --user ${xnat_user}  \
---session ${session}                \
---bids_root_dir ${bids_root_dir}
-```
-
-## Testing
-
-To run tests with Peotry, run:
-
-```
-poetry run pytest -s test
-```
-
-You will need to have a local `.env` file where you set some environment variables, e.i `XNAT_PASS`
-
-At the moment the tests can not run bids validation to do so, you can comment out the line that cleans the output directory and run the validator manually using docker.
-
-```
-bids_directory=${PWD}/tests/xnat2bids/ashenhav/study-1222/bids/
-docker run -ti --rm -v ${bids_directory}:/data:ro bids/validator /data
-```
+XNAT tools is a Python packaged developed and maintained by members of the [Behavioral Neuroimaging Core](https://brown-bnc.github.io) at Brown University. This package facilitates the export and conversion of data stored in Brown's XNAT platform to the [Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io). To learn about installation, usage and deployment please visit our [documentation](https://brown-bnc.github.io/xnat-tools/)

docs/bids_postprocess.md

@@ -0,0 +1,27 @@
+# `bids-postprocess`
+
+Script for performing post BIDSIFY processing.
+At the moment it inserts the IntendedFor field
+to JSON sidecart for fieldmap data
+
+**Usage**:
+
+```console
+$ bids-postprocess [OPTIONS] SESSION BIDS_EXPERIMENT_DIR
+```
+
+**Arguments**:
+
+* `SESSION`: XNAT Session ID, that is the Accession # for an experiment.  [required]
+* `BIDS_EXPERIMENT_DIR`: Root output directory for exporting the files  [required]
+
+**Options**:
+
+* `-S, --session-suffix TEXT`: Suffix of the session for BIDS defaults to 01.         This will produce a session label of sess-01.         You likely only need to change the default for multi-session studies  [default: 01]
+* `-i, --includeseq TEXT`: Include this participant only, can be specified multiple times  [default: ]
+* `-s, --skipseq TEXT`: Skip this participant, can be specified multiple times  [default: ]
+* `--log-file TEXT`: File to send logs to  [default: ]
+* `-v, --verbose`: Verbose level. Can be specified multiple times to increase verbosity  [default: 0]
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.