Merge pull request #38 from OSIPI/docs

Integrating MkDocs
OSIPI · Aug 8, 2024 · e484096 · e484096
2 parents d766d98 + e035d1a
commit e484096
Show file tree

Hide file tree

Showing 82 changed files with 1,458 additions and 1,436 deletions.
diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml
@@ -23,14 +23,17 @@ jobs:
         with:
           python-version: '3.10'
 
+      - name: Install Poetry
+        uses: Gr1N/setup-poetry@v8
+        with:
+          poetry-version: '1.8.3'
+
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e .[tests,docs]
+        run: poetry install --extras "tests docs"
 
-      - name: Update Sphinx htmls
+      - name: Build MkDocs documentation
         run: |
-          make html
+          poetry run mkdocs build
         working-directory: docs
 
       - name: Publish to gh-pages
@@ -39,7 +42,7 @@ jobs:
         with:
           publish_branch: gh-pages  # default: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html/
+          publish_dir: docs/site
           force_orphan: true
 
       - run: echo "Status of job = ${{ job.status }}."
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,5 @@ junit
 docs/build
 docs/source/generated
 docs/source/sg_execution_times.rst
+docs/site
+docs/generated
diff --git a/README.md b/README.md
@@ -32,6 +32,8 @@ We welcome contributions to OSIPI! To contribute, follow these steps:
 - Make your changes and commit them with descriptive messages.
 - Push your changes to your fork.
 - Submit a pull request to the main OSIPI repository.
+
+For more details on how to contribute, visit the [Developer Guide](https://osipi.github.io/pypi/developers_guide/index.html).
 #### As mentioned before, this project is still in the early stages of development. If you'd like to contribute by adding functionality, we recommend opening an issue first to discuss your proposed functionality and the best ways to implement it.
 
 ## Details

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/about/index.md b/docs/about/index.md
@@ -0,0 +1,12 @@
+# About
+
+The osipi Library is developed by the **Open Source Initiative for Perfusion Imaging (OSIPI)**, an initiative of the perfusion study group of the **International Society for Magnetic Resonance in Medicine (ISMRM)**.
+
+The osipi package structure and logic follow the lexicon defined by OSIPI, and wrap around selected implementations collected in the code contributions of OSIPI.
+
+## Scope
+
+osipi currently only includes methods for the dynamic contrast (DC) approach to perfusion MRI (DC-MRI, a unifying term for the separate fields DCE-MRI and DSC-MRI). In particular, arterial spin labelling (ASL) solutions are not currently included, but this may change in the future.
+
+!!! note "Future Updates"
+    The inclusion of arterial spin labelling (ASL) solutions may change in the future.
diff --git a/docs/source/developers_guide/index.rst → docs/contribution/index.md b/docs/source/developers_guide/index.rst → docs/contribution/index.md
diff --git a/docs/examples/.DS_Store b/docs/examples/.DS_Store
diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -0,0 +1,5 @@
+
+# Examples
+
+
+### Illustrating common use cases of osipi.
diff --git a/docs/examples/README.rst b/docs/examples/README.rst
diff --git a/docs/examples/aif/README.rst → docs/examples/aif/README.md b/docs/examples/aif/README.rst → docs/examples/aif/README.md
diff --git a/docs/examples/aif/plot_aif_parker.py b/docs/examples/aif/plot_aif_parker.py
diff --git a/docs/examples/aif/plot_dummy.py b/docs/examples/aif/plot_dummy.py
diff --git a/docs/examples/signal/plot_signal_SPGR.py b/docs/examples/signal/plot_signal_SPGR.py
diff --git a/docs/examples/signal/plot_signal_linear.py b/docs/examples/signal/plot_signal_linear.py
diff --git a/...xamples/signal_to_concentration/plot_signal_to_concentration_R1_to_C_linear_relaxivity.py b/...xamples/signal_to_concentration/plot_signal_to_concentration_R1_to_C_linear_relaxivity.py
diff --git a/docs/examples/signal_to_concentration/plot_signal_to_concentration_S_to_C_via_R1_SPGR.py b/docs/examples/signal_to_concentration/plot_signal_to_concentration_S_to_C_via_R1_SPGR.py
diff --git a/docs/examples/signal_to_concentration/plot_signal_to_concentration_S_to_R1_SPGR.py b/docs/examples/signal_to_concentration/plot_signal_to_concentration_S_to_R1_SPGR.py
diff --git a/docs/examples/tissue/README.rst → docs/examples/tissue/README.md b/docs/examples/tissue/README.rst → docs/examples/tissue/README.md
diff --git a/docs/examples/tissue/plot_extended_tofts.py b/docs/examples/tissue/plot_extended_tofts.py
diff --git a/docs/examples/tissue/plot_tofts.py b/docs/examples/tissue/plot_tofts.py
diff --git a/docs/source/_static/osipi.png → docs/img/osipi.png b/docs/source/_static/osipi.png → docs/img/osipi.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,27 @@
+# Osipi Documentation
+
+Welcome to the Osipi documentation! This guide is intended to help you get started with Osipi and provide the information you need to maximize its potential.
+
+## Warning
+
+!!! warning
+    `osipi` is developed in public but is a work in progress. This version contains mostly temporary placeholder functionality.
+
+## About Osipi
+
+`osipi` is the authoritative Python package for perfusion MRI. It is developed by the Open Source Initiative for Perfusion Imaging (OSIPI), which is a study group initiative of the International Society for Magnetic Resonance in Medicine (ISMRM).
+
+## Purpose
+
+The purpose of `osipi` is to standardize and streamline the use of perfusion MRI, ensuring consistency and reliability across different implementations and studies. The package follows the lexicon defined by OSIPI and integrates selected implementations from the original code contributions made by the OSIPI community.
+
+
+Explore the documentation to learn more about how to use `osipi` and leverage its full capabilities for your perfusion MRI projects.
+
+## Sections
+
+- [User Guide](user-guide/index.md)
+- [Contribution Guidelines](contribution/index.md)
+- [References](references/index.md)
+- [About](about/index.md)
+- [Examples](examples/index.md)
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/references/index.md b/docs/references/index.md
@@ -0,0 +1,10 @@
+# Reference
+
+This reference manual details all functions included in `osipi`, describing what they are and what they do. Documentation of individual functions contains self-contained example code that demonstrates basic usage of the function.
+
+The `osipi` package currently only includes methods for the dynamic contrast (DC) approach to perfusion MRI (DC-MRI, a unifying term for the separate fields DCE-MRI and DSC-MRI). In particular arterial spin labelling (ASL) solutions are not currently included, but may be added in the future.
+
+This reference guide, like the `osipi` package itself, adheres closely to the structure and language of the [OSIPI Lexicon](https://osipi.github.io/OSIPI_CAPLEX/).
+
+!!!warning
+    `osipi` is in development and this reference guide currently contains mainly empty placeholder entries.
diff --git a/docs/references/models.md b/docs/references/models.md
diff --git a/docs/references/models/aif_models/aif_georgiou.md b/docs/references/models/aif_models/aif_georgiou.md
@@ -0,0 +1,3 @@
+# osipi.aif_georgiou
+
+::: osipi.aif_georgiou