Merge pull request #49 from khanlab/documentation

Installation Markdowns

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+build:
+  os: 'ubuntu-20.04'
+  tools:
+    python: '3.10'
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,67 @@
+# pylint: disable=all
+# flake8: noqa
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import datetime
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+# -- Project information -----------------------------------------------------
+
+project = "Labelmerge"
+copyright = f"{datetime.date.today().year}, Arun Thurairajah"
+author = "Arun Thurairajah"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinxarg.ext",
+    "sphinxcontrib.asciinema",
+    "myst_parser",
+]
+
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+master_doc = "index"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/contributing/contributing.md

@@ -0,0 +1,60 @@
+# Contributing to Labelmerge
+
+Labelmerge python package dependencies are managed with Poetry (`v1.2.0+`), which
+you will need installed on your machine. You can find installation instructions 
+on the [Poetry website](https://python-poetry.org/docs/master/#installation).
+
+_Note: These instructions are only recommended if you are making changes to the
+Labelmerge codebase and committing these back to the repository, or if you are 
+using Snakemake's cluster execution profiles. If not, it is easier to run 
+Labelmerge using the packaged container (e.g. 
+`docker://khanlab/labelmerge:v0.4.4`)._
+
+Clone the repository and install all dependencies (including `dev`) with poetry:
+
+```
+git clone https://github.com/khanlab/labelmerge.git 
+cd labelmerge
+poetry install --with dev 
+```
+
+Poetry will automatically create a virtual environment. To customize where 
+these virtual environments are stored, see the poetry docs 
+[here](https://python-poetry.org/docs/configuration/)
+
+Then, you can run Labelmerge with:
+
+```
+poetry run labelmerge
+```
+
+or you can activate a virtual environment shell and run Labelmerge directly:
+
+```
+poetry shell
+labelmerge
+```
+
+You can exit the poetry shell with `exit`
+
+## Running and fixing code format quality
+
+Labelmerge uses [poethepoet](https://github.com/nat-n/poethepoet) as a task runner.
+You can see what commands are available by running:
+
+```
+poetry run poe 
+```
+
+We use a a few tools, including `black`, `ruff`, `isort`, `snakefmt`, and 
+`yamlfix` to ensure formatting and style of our codebase is consistent. There 
+are two task runners you can use to check and fix your code, which can be 
+invoked with:
+
+```
+poetry run poe quality-check
+poetry run poe quality
+```
+
+_Note: If you are in a poetry shell, you do not need to prepend `poetry run` to
+the command._

docs/getting_started/docker.md

@@ -0,0 +1,76 @@
+# Running Labelmerge with Docker on Windows
+
+**Note, these instructions assume you have Docker already installed on a Windows system.
+Docker can also be run on Linux or MacOS with similar commands, but here, we 
+will assume the default Windows CLI is being used.**
+
+## First time setup
+
+Open your Windows Command Prompt by clicking the `Windows` button and typing
+`cmd` and pressing the `Enter` on your keyboard. This is where you will enter 
+your commands. Feel free to make a new directory with `mkdir` or move to
+a directory you would like to work out of with `cd'. For this example, we will
+work from:
+
+```
+cd c:\Users\username\Downloads
+```
+
+Pull the container (this will take some time and storage stage, but like an 
+installation, it only needs to be done once and can then be run on many 
+datasets). The example below pulls the latest versioned container (replace 
+`latest` with `vX.X.X` for a specific version).
+
+```
+docker pull khanlab/labelmerge:latest
+```
+
+Run without any arguments to print the short help:
+
+```
+docker run -it --rm khanlab/labelmerge:latest
+```
+
+Use the `-h` option to get a detailed help listing:
+
+```
+docker run -it --rm khanlab_labelmerge_latest.sif -h
+```
+
+*Note that all the Snakemake command-line options are also available,
+and can be listed with `--help-snakemake`:*
+
+```
+docker run -it --rm khanlab_labelmerge_latest.sif --help-snakemake
+```
+
+### Explanation
+
+Everything prior to the container (`khanlab_labelmerge_latest.sif`) are arguments
+to Docker and after are to Labelmerge itself. The first three arguments to Docker
+are to enable interactive mode (`-it`), run and subsequently remove the Docker
+container upon completion (`--rm`) and mount the the directory 
+(`-v c:\Users\username\Downloads\labelmerge\test`) to a directory within the
+container named `\test`. These are not specific to Labelmerge, but are general ways
+to use Docker. You may want to familiarize yourself with 
+[Docker options](https://docs.docker.com/engine/reference/run/).
+
+The first three arguments to Labelmerge (as with any BIDS App) are the input folder 
+(`test/data/bids`), the output folder (`test/data/derivatives`), and the 
+analysis level (`participant`). 
+
+
+```
+docker run -it --rm -v c:\Users\username\Downloads\labelmerge\test:\test  khanlab_labelmerge_latest.sif /test/data/bids /test/data/derivatives participant -np
+```
+
+Now to actually run the workflow, we need to specify how many cores to use and 
+leave out the dry-run option. The Snakemake `--cores` option tells  how
+many cores to use. Using `--cores 8` means that Labelmerge will only make use of 8 
+cores at most. Generally speaking, you should use `--cores all`, so it can make 
+maximal use of all available CPU cores it has access to on your system. This is 
+especially useful if you are running multiple subjects.
+
+After this completes, you have additional folders in your output folder,
+`c:\Users\username\Downloads\labelmerge\test\data\derivatives`, for the one subject.
+

docs/getting_started/installation.md

@@ -0,0 +1,58 @@
+# Installation
+
+## Requirements
+
+* Docker (Intel Mac/Windows/Linux) or Singularity (Linux)
+
+### Notes
+* Inputs to Labelmerge should be organized as [BIDS derivatives](https://bids-specification.readthedocs.io/en/stable/05-derivatives/03-imaging.html#segmentations), taking one "base" and one "overlay" atlas
+
+## Docker on Windows / Mac (Intel) / Linux
+
+The Labelmerge BIDS App is available on DockerHub as versioned releases.
+Instructions can be found in the [Docker](https://labelmerge.readthedocs.io/en/stable/getting_started/docker.html) documentation page.
+
+### Pros
+* Compatible with non-Linux systems
+* All dependencies are in a single container
+
+### Cons
+* Typically not possible on shared machines
+* Cannot use Snakemake cluster execution profiles
+* Cannot edit code
+
+## Singularity Container
+
+The same Docker container can also be used with Singularity (now Apptainer).
+Instructions can be found in the [Singularity / Apptainer](https://labelmerge.readthedocs.io/en/stable/getting_started/singularity.html) documentation page.
+
+### Pros
+* All dependencies are in a single container, stored as a single file (.sif)
+* Compatible on shared systems with Singularity installed
+
+### Cons
+* Cannot use Snakemake cluster execution profiles
+* Cannot edit code
+
+## Python Environment with Singularity Dependencies
+
+Instructions can be found in the [Contributing](https://labelmerge.readthedocs.io/en/stable/contributing/contributing.html) documentation page.
+
+### Pros
+* Flexibility to modify code
+
+### Cons
+* Only compatible on systems with Singularity for external dependencies
+
+## Pip Install
+`labelmerge` can also be installed using pip:
+
+```bash
+pip install labelmerge
+```
+
+### Pros
+* Ease of installation
+
+### Cons
+* Potential for conflicting dependencies across different packages