Add rtd and sphinx (#23)

* added sphinx for rtd
* updated readme, removed utils.bids.py
* standardizing docstring formatting
* start laying out RTD site
* add rtd config, update pyproject.toml
* add linting and spellcheck
* fix spelling, ignore poetry.lock

.github/workflows/build-docs-with-actions.yaml

@@ -0,0 +1,47 @@
+# We want to make sure that a user is able to build the docs locally before pushing to RTD.
+# Additionally, this helps us to better determine if there is an issue with the RTD build 
+# versus an issue with sphinx and mkdocs itself.
+name: Build Docs with Actions
+
+on:
+    push:
+        branches:
+            - '**'
+
+jobs:
+    build-install:
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-latest]
+            # we only use 3.9 for RTD at this time.
+            python-version: ["3.9"]
+
+        steps:
+          - name: Checkout repository
+            uses: actions/checkout@v2
+
+          - name: Set up Python
+            uses: actions/setup-python@v2
+            with:
+              python-version: ${{ matrix.python-version }}
+
+          - name: Check python3 == python${{ matrix.python-version }}
+            run: |
+              installed_python=$(python3 --version)
+              echo "Installed Python: $installed_python"
+              if [[ "$installed_python" != *"${{ matrix.python-version }}"* ]]; then
+                echo "Python version mismatch. Expected: ${{ matrix.python-version }}, but got: $installed_python"
+                exit 1
+              fi
+
+          - name: Install Poetry
+            run: |
+              curl -sSL https://install.python-poetry.org | python3 -
+
+          - name: Install Dependencies
+            run: |
+                poetry install --with dev
+
+          - name: Build Docs
+            run: make docs

.github/workflows/lint-and-spellcheck.yaml

@@ -0,0 +1,40 @@
+# Codespell configuration is within .codespellrc
+name: Lint and Spellcheck
+
+on:
+    push:
+      branches: 
+        - '**'
+    pull_request:
+      branches: [main]
+
+permissions:
+    contents: read
+
+jobs:
+  lintandspell:
+    name: Check for spelling and formatting errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Annotate locations with typos
+        uses: codespell-project/codespell-problem-matcher@v1
+
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+            exclude_file: poetry.lock
+
+      - name: Install Poetry
+        run: |
+            curl -sSL https://install.python-poetry.org | python3 -
+
+      - name: Install Dependencies
+        run: |
+            poetry install --with dev
+
+      - name: Lint files with Black
+        run: make check-black

.gitignore

@@ -11,3 +11,12 @@ venv/
 *strace*
 run_docker_*
 testdata/
+
+# .gitignore
+
+# Sphinx build directory
+docs/_build/
+
+# Sphinx cache
+docs/.doctrees
+docs/.buildinfo

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.9"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+      - poetry config virtualenvs.create false
+    post_install:
+      - poetry install --with dev
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py

Makefile

@@ -1,9 +1,12 @@
 # Quickly run black on all python files in this repository, local version of the pre-commit hook
 black:
 	@for file in `find . -name "*.py"`; do \
-		black $$file; \
+		poetry run black $$file; \
 	done
 
+check-black:
+	poetry run black --check . --exclude="dist/*" --exclude="build/*" --exclude="docs/*";
+
 # install python dependencies
 pythondeps:
 	pip install --upgrade pip && pip install  -e .
@@ -20,6 +23,14 @@ 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
 
+.PHONY: docs
+docs:
+	poetry run sphinx-build -b html docs docs/_build/html
+
+.PHONY: docs-serve
+docs-serve:
+	poetry run sphinx-autobuild docs docs/_build/html
+
 # runs github actions ci locally using nektos/act
 # needs to be installed with brew install act on mac
 # install instructions for other platforms can be found here:

README.md

@@ -124,7 +124,7 @@ Option to merge TACs across runs for each subject within a single session.
 
 #### `--docker`
 
-Indicates the script will run within a Docker container that contains all of the necessary dependencies for this project. A version of FreeSurfer should stil be installed along with a valid license. If you have difficulty using this extra option below is an example of an "unwrapped" command to execute this pipeline in Docker.
+Indicates the script will run within a Docker container that contains all of the necessary dependencies for this project. A version of FreeSurfer should still be installed along with a valid license. If you have difficulty using this extra option below is an example of an "unwrapped" command to execute this pipeline in Docker.
 
 ```bash
 docker run -a stderr -a stdout --rm \ 

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,78 @@
+# 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 = "petprep_extract_tacs"
+copyright = "2024, Martin Norgaard"
+author = "Martin Norgaard"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+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"]
+
+
+def get_opt_fwhm(opt_params):
+    """
+    Obtain optimal FWHM values from a parameters file.
+
+    :param opt_params: Path to the file containing optimal FWHM parameters.
+    :type opt_params: str
+    :return: A tuple containing:
+
+        - **fwhm_x** (*float*): FWHM value along the x-axis.
+        - **fwhm_y** (*float*): FWHM value along the y-axis.
+        - **fwhm_z** (*float*): FWHM value along the z-axis.
+        - **tsv_file** (*str*): Path to the generated TSV file with FWHM values.
+    :rtype: tuple
+
+    :notes:
+        This function reads the optimal FWHM parameters from the given file, creates a DataFrame,
+        saves it as a TSV file named `pvc-agtm_desc-fwhm_confounds.tsv` in the current working directory,
+        and returns the FWHM values along with the path to the TSV file.
+    """
+    import os
+    import pandas as pd
+
+    new_pth = os.getcwd()
+
+    with open(opt_params, "r") as file:
+        contents = file.read()
+
+    # Extracting the FWHM values for x, y, and z from the file
+    fwhm_values = contents.split()
+
+    # Assigning the values to fwhm_x, fwhm_y, and fwhm_z
+    fwhm_x, fwhm_y, fwhm_z = map(float, fwhm_values)
+
+    fwhm = pd.DataFrame({"fwhm_x": [fwhm_x], "fwhm_y": [fwhm_y], "fwhm_z": [fwhm_z]})
+
+    fwhm.to_csv(
+        os.path.join(new_pth, "pvc-agtm_desc-fwhm_confounds.tsv"), sep="\t", index=False
+    )
+
+    tsv_file = os.path.join(new_pth, "pvc-agtm_desc-fwhm_confounds.tsv")
+
+    return fwhm_x, fwhm_y, fwhm_z, tsv_file

docs/index.rst

@@ -0,0 +1,83 @@
+.. petprep_extract_tacs documentation master file, created by
+   sphinx-quickstart on Tue Nov 26 14:20:42 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to petprep_extract_tacs's documentation!
+================================================
+
+Overview
+--------
+
+This BIDS App is designed to extract time activity curves (TACs) from PET data. The workflow has options to extract TACs from different regions of the brain, and it uses the Brain Imaging Data Structure (BIDS) standard for organizing and describing the data. This README will guide you through how to use the app and the various options available. The workflow requires that freesurfer's recon-all was already executed for these subjects, and exist as a 'freesurfer' directory inside the derivatives directory for the given BIDS dataset.
+
+Features
+---------
+
+  * BIDS compliant PET data input and output
+  * Time Activity Curve extraction from various brain regions
+  * Options for both surface and volume-based extractions including smoothing options
+
+Requirements
+------------
+
+  * Python 3.9+
+  * FreeSurfer v. 7.3.2
+  * MATLAB RUNTIME (`sudo fs_install_mcr R2019b` when FreeSurfer is installed)
+
+Installation
+------------
+
+Clone the repository and install the required packages:
+
+.. code-block:: bash
+
+   git clone
+   git clone https://github.com/mnoergaard/petprep_extract_tacs.git
+   cd petprep_extract_tacs
+   pip install -e .
+
+The package is also pip installable and can be installed using the following command
+
+.. code-block:: bash
+   
+   pip install petprep-extract-tacs
+
+
+Quickstart
+----------
+
+After installation, you'll need to have your data organized according to the BIDS standard. Once that's in place, you can run the app like this:
+
+.. code-block:: bash
+
+   petprep_extract_tacs /path/to/your/bids/dataset /path/to/output/dir --n_procs 4 --wm
+
+Alternatively, you can run the code directly with Python using the `run.py` entrypoint:
+
+.. code-block:: bash
+
+   python3 run.py /path/to/your/bids/dataset /path/to/output/dir --n_procs 4 --wm
+
+This will run the app on your BIDS dataset and save the output to the specified directory. Additional region-specific and smoothing options can be specified as detailed below.
+
+.. _usage_page: usage.html
+
+For more detailed usage see the usage_page_ section.
+
+
+.. toctree::
+   usage
+   petprep_extract_tacs
+   utils
+   interfaces
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/interfaces.rst

@@ -0,0 +1,36 @@
+.. _interfaces:
+
+interfaces
+==========
+
+fs_model
+--------
+
+.. automodule:: petprep_extract_tacs.interfaces.fs_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fs_preprocess
+-------------
+
+.. automodule:: petprep_extract_tacs.interfaces.fs_preprocess
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+petsurfer
+---------
+
+.. automodule:: petprep_extract_tacs.interfaces.petsurfer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+segment
+-------
+
+.. automodule:: petprep_extract_tacs.interfaces.segment
+   :members:
+   :undoc-members:
+   :show-inheritance: