Merge pull request #37 from BrainLesion/36-enhance-docs

36 enhance docs

.github/workflows/tests.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4

README.md

@@ -1,12 +1,12 @@
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/brats?logo=python&color=2EC553)](https://pypi.org/project/brats/)
-[![Documentation Status](https://readthedocs.org/projects/brats/badge/?version=latest&color=2EC553)](http://brats.readthedocs.io/?badge=latest)
+# BraTS
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/brats)](https://pypi.org/project/brats/)
+[![Stable Version](https://img.shields.io/pypi/v/brats?label=stable)](https://pypi.python.org/pypi/brats/)
+[![Documentation Status](https://readthedocs.org/projects/brats/badge/?version=latest)](http://brats.readthedocs.io/?badge=latest)
 [![tests](https://github.com/BrainLesion/brats/actions/workflows/tests.yml/badge.svg)](https://github.com/BrainLesion/brats/actions/workflows/tests.yml)
-[![PyPI version brats-algorithms](https://img.shields.io/pypi/v/brats?color=2EC553)](https://pypi.python.org/pypi/brats/)
 [![codecov](https://codecov.io/gh/BrainLesion/BraTS/graph/badge.svg?token=A7FWUKO9Y4)](https://codecov.io/gh/BrainLesion/BraTS)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# BraTS
-
 Providing the top performing algorithms from the Brain Tumor Segmentation (BraTS) challenges, through an easy to use Python API powered by docker.
 
 ## Features
@@ -19,16 +19,19 @@ Providing the top performing algorithms from the Brain Tumor Segmentation (BraTS
 
 With a Python 3.8+ environment, you can install `brats` directly from [PyPI](https://pypi.org/project/brats/):
 
-```sh
+```bash
 pip install brats
 ```
 
-### Docker and NVIDIA Container Toolkit Setup
+> [!IMPORTANT]  
+> To run `brats` you require a Docker installation. <br>
+> Many algorithms also require GPU support (NVIDIA Docker). <br>
+> In case you do not have access to a Cuda-capable GPU, the overview tables in the [Algorithms](#algorithms) section indicate which algorithms are CPU compatible.
+
 
-To run `brats` you need a working Docker installation.
-Most algorithms also require GPU support (NVIDIA Docker).
 
-Installation instructions:
+
+### Docker and NVIDIA Container Toolkit Setup
 
 - **Docker**: Installation instructions on the official [website](https://docs.docker.com/get-docker/)
 - **NVIDIA Container Toolkit**: Refer to the [NVIDIA install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) and the official [GitHub page](https://github.com/NVIDIA/nvidia-container-toolkit)
@@ -61,72 +64,69 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> Adult Glioma Segmentation </strong> </summary>
 <br>
 
-**Class:** `brats.AdultGliomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.segmentation_algorithms.AdultGliomaSegmenter))
-
+**Class:** `brats.AdultGliomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.AdultGliomaSegmenter))
 
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AdultGliomaAlgorithms)|
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _André Ferreira, et al._ | [Link](https://arxiv.org/abs/2402.17317v1) | &#x274C; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Andriy Myronenko, et al._ | N/A | &#x274C; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Fadillah Adamsyah Maani, et al._ | N/A | &#x274C; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_3) |
+| Year | Rank | Author                            | Paper                                      | CPU Support | Key Enum |
+| ---- | ---- | --------------------------------- | ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| 2023 | 1st  | _André Ferreira, et al._          | [Link](https://arxiv.org/abs/2402.17317v1) | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Andriy Myronenko, et al._        | N/A                                        | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Fadillah Adamsyah Maani, et al._ | N/A                                        | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_3) |
 
 </details>
 
 <details>
 <summary> <strong> BraTS-Africa Segmentation </strong> </summary>
 <br>
 
-**Class:** `brats.AfricaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.segmentation_algorithms.AfricaSegmenter))
+**Class:** `brats.AfricaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.AfricaSegmenter))
 
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AfricaAlgorithms)|
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _Andriy Myronenko, et al._ | TODO | &#x274C; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AfricaAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Alyssa R Amod, et al._ | N/A | &#x274C; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AfricaAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Ziyan Huang, et al._ | N/A | &#x2705; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.AfricaAlgorithms.BraTS23_3) |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
+| ---- | ---- | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| 2023 | 1st  | _Andriy Myronenko, et al._ | TODO  | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Alyssa R Amod, et al._    | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_3) |
 
 </details>
 
 <details>
 <summary> <strong> Meningioma Segmentation </strong> </summary>
 <br>
 
-**Class:** `brats.MeningiomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.segmentation_algorithms.MeningiomaSegmenter))
-
+**Class:** `brats.MeningiomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.MeningiomaSegmenter))
 
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MeningiomaAlgorithms)|
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _Andriy Myronenko, et al._ | N/A | &#x274C; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Ziyan Huang, et al._ | N/A | &#x2705; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Zhifan Jiang et al._ | N/A | &#x274C; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_3) |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
+| ---- | ---- | -------------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 2023 | 1st  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Zhifan Jiang et al._      | N/A   | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_3) |
 
 </details>
 
 <details>
 <summary> <strong> Brain Metastases Segmentation </strong> </summary>
 <br>
 
-**Class:** `brats.MetastasesSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.segmentation_algorithms.MetastasesSegmenter))
+**Class:** `brats.MetastasesSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.MetastasesSegmenter))
 
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MetastasesAlgorithms)|
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _Andriy Myronenko, et al._ | N/A | &#x274C; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Siwei Yang, et al._ | N/A | &#x274C; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Ziyan Huang, et al._ | N/A | &#x2705; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_3) |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
+| ---- | ---- | -------------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 2023 | 1st  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Siwei Yang, et al._       | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_3) |
 
 </details>
 
 <details>
 <summary> <strong> Pediatric Segmentation </strong> </summary>
 <br>
 
-**Class:** `brats.PediatricSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.segmentation_algorithms.PediatricSegmenter))
+**Class:** `brats.PediatricSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.PediatricSegmenter))
 
-
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.PediatricAlgorithms)|
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _Zhifan Jiang et al._ | N/A | &#x274C; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.PediatricAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Andriy Myronenko, et al._ | N/A | &#x274C; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.PediatricAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Yubo Zhou_ | N/A | &#x274C; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.PediatricAlgorithms.BraTS23_3) |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
+| ---- | ---- | -------------------------- | ----- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| 2023 | 1st  | _Zhifan Jiang et al._      | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Yubo Zhou_                | N/A   | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_3) |
 
 </details>
 
@@ -136,18 +136,16 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> Inpainting </strong> </summary>
 <br>
 
-**Class:** `brats.Inpainter` ([Docs](https://brats.readthedocs.io/en/latest/algorithms.html#brats.core.inpainting_algorithms.Inpainter))
-
-| Year | Rank | Author | Paper | CPU Support | [Key Enum](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.InpaintingAlgorithms) |
-|------|-------|--------|-------|-------------|-------------|
-| 2023 | 1st | _Juexin Zhang, et al._ | N/A | &#x2705; | [BraTS23_1](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_1) |
-| 2023 | 2nd | _Alicia Durrer, et al._ | N/A | &#x274C; | [BraTS23_2](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_2) |
-| 2023 | 3rd | _Jiayu Huo, et al._ | N/A | &#x2705; | [BraTS23_3](https://brats.readthedocs.io/en/latest/constants.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_3) |
+**Class:** `brats.Inpainter` ([Docs](https://brats.readthedocs.io/en/latest/core/inpainting_algorithms.html#brats.core.inpainting_algorithms.Inpainter))
 
+| Year | Rank | Author                  | Paper | CPU Support | Key Enum         |
+| ---- | ---- | ----------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 2023 | 1st  | _Juexin Zhang, et al._  | N/A   | &#x2705;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Alicia Durrer, et al._ | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Jiayu Huo, et al._     | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_3) |
 
 </details>
 
-
 ## Citation
 
 If you use BraTS in your research, please cite it to support the development!

docs/source/conf.py

@@ -5,9 +5,14 @@
 
 import os
 import sys
+from subprocess import run
+
 
 sys.path.insert(0, os.path.abspath("../../"))
 
+
+run(["python", "preprocess_readme.py"])
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -33,8 +38,8 @@
 # -- 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"]
+html_theme = "furo"
+# html_static_path = ["_static"]
 
 autodoc_default_options = {
     "members": True,

docs/source/core/brats_algorithm.rst

@@ -0,0 +1,6 @@
+Abstract Base Class
+====================
+
+The following class represents the abstract base class for BraTS algorithms.
+
+.. automodule:: brats.core.brats_algorithm

docs/source/core/core.rst

@@ -0,0 +1,13 @@
+Core
+========================
+
+The following classes provide the top performing algorithms from several BraTS challenges.
+All algorithms can be used for a single subject inference (one set of MRI scans) or for a batch of multiple subjects.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Core Algorithms
+
+   segmentation_algorithms
+   inpainting_algorithms
+   brats_algorithm

docs/source/core/inpainting_algorithms.rst

@@ -0,0 +1,6 @@
+Inpainting Algorithms
+======================
+
+The following classes provide inpainting algorithms from several BraTS challenges.
+
+.. automodule:: brats.core.inpainting_algorithms

docs/source/core/segmentation_algorithms.rst

@@ -0,0 +1,6 @@
+Segmentation Algorithms
+========================
+
+The following classes provide segmentation algorithms from several BraTS challenges.
+
+.. automodule:: brats.core.segmentation_algorithms

docs/source/index.rst

@@ -6,26 +6,25 @@
 BraTS documentation
 ===================
 
-.. include:: ../../README.md
+.. include:: ../README_preprocessed.md
    :parser: myst_parser.sphinx_
 
-.. toctree::
-   :maxdepth: 4
-   :caption: Contents:
 
+Sections
+===================
 
 
-Indices and tables
-===================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started:
+
+   readme
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: API Reference:
 
-   algorithms
-   constants
+   core/core
+   utils/utils
 

docs/source/preprocess_readme.py

@@ -0,0 +1,36 @@
+import re
+
+
+def preprocess_readme(input_file: str, output_file: str) -> None:
+    """Preprocess a README file to replace GitHub admonitions with Sphinx-style admonitions.
+
+    Args:
+        input_file (str): original README file
+        output_file (str): processed README file
+
+    """
+    with open(input_file, "r") as file:
+        content = file.read()
+
+    admonition_types = ["IMPORTANT", "NOTE", "TIP", "WARNING", "CAUTION"]
+
+    for ad_type in admonition_types:
+        # Replace > [!ad_type] with Sphinx admonition syntax
+        content = re.sub(
+            r"> \[!"
+            + ad_type
+            + "\]\s*\n((?:> .*\n)*)",  # Match the > [!ad_type] and subsequent lines
+            lambda m: "```{"
+            + ad_type
+            + "}\n"
+            + m.group(1).replace("> ", "").strip()
+            + "\n```",  # Replace with MyST syntax
+            content,
+        )
+    # Write the transformed content to the output file
+    with open(output_file, "w") as file:
+        file.write(content)
+
+
+if __name__ == "__main__":
+    preprocess_readme("../../README.md", "../README_preprocessed.md")

docs/source/readme.rst

@@ -0,0 +1,6 @@
+Readme 
+==============
+
+
+.. include:: ../README_preprocessed.md
+   :parser: myst_parser.sphinx_

docs/source/constants.rst → docs/source/utils/utils.rst

@@ -1,8 +1,15 @@
-Constants
+Utils
 ========================
 
-Constants used in the package
+Constants
 ------------------------------
 
 .. automodule:: brats.utils.constants 
+    :members:
+
+
+Exceptions
+------------------------------
+
+.. automodule:: brats.utils.exceptions 
     :members: