Modernize docs, testing, and data handling

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,test]"
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+
+      - name: Run pytest
+        run: pytest

.readthedocs.yaml

@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-  configuration: pytheranostics/docs/source/conf.py
+  configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:
@@ -29,9 +29,7 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
    install:
-    - requirements: requirements.txt
-    - requirements: pytheranostics/docs/requirements.txt
     - method: pip
       path: .
-    # - method: pip
-    #  requirements: -r pytheranostics/docs/requirements.txt
+      extra_requirements:
+        - docs

docs/source/API/modules.rst

@@ -0,0 +1,84 @@
+DICOM Tools
+===========
+
+.. automodule:: pytheranostics.dicomtools.dicomtools
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dicomtools.dicom_receiver
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Calibrations
+============
+
+.. automodule:: pytheranostics.calibrations.gamma_camera
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Dosimetry
+=========
+
+.. automodule:: pytheranostics.dosimetry.base_dosimetry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.bone_marrow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.dosiomicsclass
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.dvk
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.image_analysis
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.mc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.olinda
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.organ_s_dosimetry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.dosimetry.voxel_s_dosimetry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Fitting
+=======
+
+.. automodule:: pytheranostics.fits.fits
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: pytheranostics.fits.functions
+   :members:
+   :undoc-members:
+   :show-inheritance:

pytheranostics/docs/source/conf.py → docs/source/conf.py

@@ -4,6 +4,7 @@
 import sys
 
 sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath("."))
 
 
 # -- Project information -----------------------------------------------------
@@ -25,10 +26,20 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.mathjax",
+    "myst_parser",
+    "nbsphinx",
+    "sphinx_copybutton",
 ]
 
 templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**/.ipynb_checkpoints"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+autodoc_mock_imports = ["radiomics", "gatetools", "itk"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -52,3 +63,45 @@
 napoleon_use_param = True
 napoleon_use_rtype = True
 napoleon_type_aliases = None
+
+nbsphinx_execute = "never"
+nbsphinx_allow_errors = False
+nbsphinx_codecell_lexer = "python"
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+
+_CONTRIB_EXTENSION = "sphinxcontrib.contributors"
+try:
+    __import__(_CONTRIB_EXTENSION)
+except ImportError:  # pragma: no cover - optional dependency
+    _contributors_available = False
+else:
+    _contributors_available = True
+    extensions.append(_CONTRIB_EXTENSION)
+
+
+def setup(app):
+    """Register a fallback contributors directive when the extension is missing."""
+    if _contributors_available:
+        return
+
+    from docutils import nodes
+    from docutils.parsers.rst import Directive
+
+    class _ContributorsDirective(Directive):
+        has_content = False
+        required_arguments = 1
+
+        def run(self):
+            repo = self.arguments[0]
+            paragraph = nodes.paragraph()
+            paragraph += nodes.Text(
+                "Install 'sphinx-contributors' to render the contributors list. "
+                f"In the meantime see https://github.com/{repo}/graphs/contributors."
+            )
+            return [paragraph]
+
+    app.add_directive("contributors", _ContributorsDirective)

pytheranostics/docs/source/extensions/sphinx_github_contributors.py → docs/source/extensions/sphinx_github_contributors.py

@@ -5,6 +5,7 @@
 
 
 def fetch_github_contributors(app):
+    """Fetch contributors via the GitHub API and write a simple RST list."""
     username = app.config.github_username
     repository = app.config.github_repository
     output_file = app.config.contributors_output_file
@@ -40,6 +41,7 @@ def fetch_github_contributors(app):
 
 
 def setup(app):
+    """Register config values and connect the fetch hook."""
     app.add_config_value("github_username", None, "env")
     app.add_config_value("github_repository", None, "env")
     app.add_config_value("contributors_output_file", "../contributors.rst", "env")

pytheranostics/docs/source/index.rst → docs/source/index.rst

@@ -3,20 +3,30 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PyTheranostics's documentation!
-=======================================
+PyTheranostics Documentation
+============================
 
 PyTheranostics is a comprehensive Python library for nuclear medicine image processing and dosimetry calculations. It provides a complete workflow from image processing to absorbed dose calculations in target organs.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Getting Started
 
-   installation
-   quickstart
-   modules
-   api
-   contributing
+   intro/overview
+   intro/installation
+   usage/basic_usage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials
+
+   tutorials/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   API/modules
    changelog
 
 Features
@@ -31,7 +41,7 @@ Features
 * Visualization and plotting capabilities
 
 Installation
------------
+------------
 
 You can install PyTheranostics using pip:
 
@@ -46,7 +56,7 @@ For development installation:
    pip install -e ".[dev]"
 
 Quick Start
-----------
+-----------
 
 .. code-block:: python
 
@@ -76,11 +86,9 @@ This project is licensed under the terms of the MIT license. See the `LICENSE <h
 Acknowledgements
 ----------------
 
-We would like to thank the following contributors for their work on this project:
-
-..  contributors:: qurit/PyTheranostics
-   .. :avatars:
-   .. :exclude: dependabot[bot]
+We would like to thank everyone who has contributed to PyTheranostics. Visit the
+`GitHub contributors graph <https://github.com/qurit/PyTheranostics/graphs/contributors>`_
+for the up-to-date list of collaborators.
 
 .. footer::
 

pytheranostics/docs/source/tutorials/SPECT2SUV/SPECT2SUV.ipynb → docs/source/tutorials/SPECT2SUV/SPECT2SUV.ipynb

@@ -36,9 +36,21 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "spect_counts='/mnt/c/Users/curibe/Nextcloud/BCCancer/CodeRepositories/doodle/doodle/documentation/testimages/016.dcm'\n",
+    "from pathlib import Path\n",
     "\n",
-    "output_path='./test016.dcm'"
+    "def _find_examples_dir() -> Path:\n",
+    "    candidates = [\n",
+    "        Path.cwd() / \"examples\" / \"data\",\n",
+    "        Path.cwd() / \"docs\" / \"source\" / \"examples\" / \"data\",\n",
+    "    ]\n",
+    "    for candidate in candidates:\n",
+    "        if candidate.exists():\n",
+    "            return candidate\n",
+    "    raise FileNotFoundError(\"Could not locate docs example data directory\")\n",
+    "\n",
+    "EXAMPLES_DIR = _find_examples_dir()\n",
+    "spect_counts = str(EXAMPLES_DIR / \"testimages\" / \"016.dcm\")\n",
+    "output_path = str(Path.cwd() / \"test016.dcm\")\n"
    ]
   },
   {
@@ -168,4 +180,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/source/tutorials/index.rst

@@ -0,0 +1,12 @@
+Tutorials
+=========
+
+Hands-on walkthroughs that demonstrate common PyTheranostics workflows. The
+notebooks are rendered directly in the documentation via nbsphinx.
+
+.. toctree::
+   :maxdepth: 1
+
+   SPECT2SUV/SPECT2SUV
+   ROI_Mapping_Tutorial/ROI_Mapping_Tutorial
+   Data_Ingestion_Examples/Data_Ingestion_Examples

pyproject.toml

@@ -38,6 +38,22 @@ dependencies = [
 "Bug Tracker" = "https://github.com/qurit/PyTheranostics/issues"
 
 [project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=1.0",
+    "sphinx-autodoc-typehints>=2.0",
+    "nbsphinx>=0.9",
+    "nbconvert>=7.0",
+    "myst-parser>=2.0",
+    "sphinx-copybutton>=0.5",
+    "sphinx-contributors>=0.1",
+    "pandoc>=2.4",
+    "ipython>=8.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -50,16 +66,28 @@ dev = [
     "pre-commit>=3.0.0",
     "sphinx>=7.0",
     "sphinx-rtd-theme>=1.0",
+    "sphinx-autodoc-typehints>=2.0",
+    "nbsphinx>=0.9",
+    "nbconvert>=7.0",
+    "myst-parser>=2.0",
+    "sphinx-copybutton>=0.5",
+    "sphinx-contributors>=0.1",
+    "pandoc>=2.4",
+    "ipython>=8.0",
     "pydocstyle>=6.0",
     "flake8-docstrings>=1.7"
 ]
 
+[tool.hatch.build]
+include = ["pytheranostics/data/**/*"]
+
 [tool.hatch.build.targets.wheel]
 packages = [
     "pytheranostics",
     "pytheranostics.calibrations",
     "pytheranostics.dicomtools",
     "pytheranostics.dosimetry",
+    "pytheranostics.data",
     "pytheranostics.fits",
     "pytheranostics.plots",
     "pytheranostics.qc",

pytheranostics/calibrations/__init__.py

@@ -0,0 +1 @@
+"""PyTheranostics package."""