23 doc improve documentation with readthedocs

.github/workflows/readthedocs.yaml

@@ -0,0 +1,22 @@
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+permissions:
+  pull-requests: write
+
+jobs:
+  pull-request-links:
+  runs-on: ubuntu-latest
+  steps:
+    -uses: readthedocs/actions/preview@v1
+     with:
+      project-slug: "readthedocs-preview"

.gitignore

@@ -35,4 +35,8 @@ integration_testing.sh
 petdeface/Dockerfile
 petdeface/README.md
 petdeface/pyproject.toml
-freesurfer_binaries/*
+freesurfer_binaries/*
+
+# ignore html files that are generated by sphinx "make html"
+docs/_build/
+*.doctree

Makefile

@@ -28,4 +28,7 @@ dockerbuild:
 
 dockerpush: dockerbuild
 	docker push openneuropet/$(shell cat pyproject.toml | grep name | cut -d '"' -f 2):$(shell cat pyproject.toml | grep version | head -n 1 | cut -d '"' -f 2)
-	docker push openneuropet/$(shell cat pyproject.toml | grep name | cut -d '"' -f 2):latest
+	docker push openneuropet/$(shell cat pyproject.toml | grep name | cut -d '"' -f 2):latest
+
+html:
+	cd docs && make html

README.md

@@ -24,6 +24,8 @@ This software can be installed via source or via pip from PyPi with `pip install
 *for a full list of dependencies see the pyproject.toml in this repo*
 
 ## Usage
+**_NOTE:_** This project is currently in beta release, some features listed below may not be available for version numbers < 1.0.0
+
 ```bash
 usage: petdeface.py [-h] [--output_dir OUTPUT_DIR] [--anat_only]
        [--subject SUBJECT] [--session SESSION] [--docker]
@@ -47,7 +49,7 @@ options:
   --docker, -d          Run in docker container
   --n_procs N_PROCS     Number of processors to use when running the workflow
   --skip_bids_validator
-  --version, -v         show program's version number and exit
+  --version, -v         show programs version number and exit
   --placement PLACEMENT, -p PLACEMENT
                         Where to place the defaced images. Options are
                         'adjacent': next to the input_dir (default) in a folder appended with _defaced
@@ -57,6 +59,45 @@ options:
   --remove_existing, -r Remove existing output files in output_dir.
 ```
 
+Working example usage:
+
+```bash
+petdeface /inputfolder --output_dir /outputfolder --n_procs 16 --skip_bids_validator --placement adjacent
+```
+
+### Docker Usage
+
+Requirements:
+- Docker must be installed and access to `docker run` must be available to the current user
+- `openneuropet/petdeface` must be present or reachable at dockerhub from the machine the cli is installed at, e.g. `docker pull openneuropet/petdeface` must work
+- if one is unable to pull the image on can build locally with `make dockerbuild`
+
+**_NOTE:_** The docker image for petdeface is not intended to be used by itself, but instead accessed via the `petdeface` command line written in Python.
+
+Appending the `--docker` after including all of the required arguments for petdeface will 
+automatically launch the dockerized version of this application, no additional input after
+that is required.
+
+**Running directly with Docker, no Python, no installation:**
+
+If you run without using the CLI you will need to:
+- bind the input and output volumes to the container
+- bind a freesurfer license to the container at `/opt/freesurfer/license.txt`
+- provide all of the arguments you would normally need to provide to the Python CLI
+- provide $UID and $GID if running on linux so that your output isn't written as root, you may disregard this if you're handy.
+
+An example of the command generated from the Python cli to run the docker based version can
+be seen below:
+
+```bash
+docker run --user=$UID:$GID -a stderr -a stdout --rm \
+-v /Data/faced_pet_data/:/input \
+-v /Data/defaced_pet_data/:/output \
+-v /home/freesurfer/license.txt:/opt/freesurfer/license.txt \
+--platform linux/amd64 \
+petdeface:latest  /input --output_dir /output --n_procs 16 --skip_bids_validator  --placement adjacent --user=$UID:$GID system_platform=Linux
+```
+
 ## Development
 
 This project uses poetry to package and build, to create a pip installable version of the package run:

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,40 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "petdeface"
+copyright = "2023, OpenNeuroPET"
+author = "Martin Nørgaard, Anthony Galassi, Murat Bilgel"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# get absolute path to python project files
+import pathlib
+import os
+import sys
+
+python_project_path = pathlib.Path(os.path.abspath("../petdeface/petdeface"))
+sys.path.insert(0, str(python_project_path))
+
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx_rtd_theme",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,22 @@
+.. petdeface documentation master file, created by
+   sphinx-quickstart on Wed Dec  6 14:28:30 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to petdeface's documentation!
+=====================================
+
+.. toctree::
+   installation
+   modules
+   usage
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,37 @@
+.. _installation:
+
+Installation
+============
+
+.. _PyPi: https://pypi.org/project/petdeface/
+
+PETdeface can be installed via PyPi_::
+
+    pip install petdeface
+
+Or cloned and installed from source::
+
+    git clone https://github.com/openneuropet/petdeface.git
+    cd petdeface
+    poetry build
+    pip install dist/petdeface-<X.X.X>-py3-none-any.whl 
+    # where X.X.X is the version number of the generated file
+
+Dependencies
+------------
+
+- FreeSurfer_ and MiDeFAce_ >= 7.3
+
+.. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/ 
+.. _MiDeFace: https://surfer.nmr.mgh.harvard.edu/fswiki/MiDeFace
+
+- Nipype_ >= 1.6.0
+
+.. _Nipype: https://nipype.readthedocs.io/en/latest/
+
+Optional Dependencies
+---------------------
+
+- Docker_
+
+.. _Docker: https://www.docker.com/

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules.rst

@@ -0,0 +1,31 @@
+.. _modules:
+
+PETdeface
+=========
+
+Submodules
+----------
+
+petdeface.mideface module
+-------------------------
+
+.. automodule:: petdeface.mideface
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+petdeface.pet module
+--------------------
+
+.. automodule:: petdeface.pet
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+petdeface.petdeface module
+--------------------------
+
+.. automodule:: petdeface.petdeface
+    :members:
+    :undoc-members:
+    :show-inheritance: