docs\feat: #48 docs formatter

- applied formatter to docs
blotero · Apr 22, 2024 · c4871a7 · c4871a7
1 parent aa06028
commit c4871a7
Show file tree

Hide file tree

Showing 8 changed files with 198 additions and 172 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,7 @@
 alabaster==0.7.13
 annotated-types==0.6.0
 Babel==2.13.1
+black==24.4.0
 certifi==2023.11.17
 charset-normalizer==3.3.2
 click==8.1.7
@@ -12,14 +13,18 @@ Jinja2==3.1.2
 markdown-it-py==3.0.0
 MarkupSafe==2.1.3
 mdurl==0.1.2
+mypy-extensions==1.0.0
 packaging==23.2
+pathspec==0.12.1
+platformdirs==4.2.0
 pydantic==2.5.2
 pydantic_core==2.14.5
 Pygments==2.17.2
 requests==2.31.0
 rich==13.7.0
 rstcheck==6.2.0
 rstcheck-core==1.2.0
+rstfmt==0.0.14
 shellingham==1.5.4
 snowballstemmer==2.2.0
 Sphinx==7.2.6

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -5,6 +5,7 @@
 
 extensions = [
     "sphinx_rtd_theme",
+    'sphinx.ext.mathjax',
 ]
 
 templates_path = ["_templates"]

diff --git a/docs/source/contribution.rst b/docs/source/contribution.rst
@@ -1,93 +1,103 @@
-Contribution
-============
+##############
+ Contribution
+##############
 
+If you want to contribute to this project, please consider the following
+practices according to your contribution target.
 
-If you want to contribute to this project, please consider the following practices
-according to your contribution target.
+******
+ Core
+******
 
+The ``core/`` directory contains all functionalities for training and
+running the semantic segmentation model. Core behaves like a python
+module. For contributing to this section, first setup your development
+environment as follows:
 
-Core
-----
-The ``core/`` directory contains all functionalities for training and running the
-semantic segmentation model. Core behaves like a python module. 
-For contributing to this section, first setup your development environment as follows:
+.. code:: bash
 
-.. code-block:: bash
-
-    cd core/
-    python -m venv .env
-    source .env/bin/activate
-    pip install -r requirements.txt
-    
+   cd core/
+   python -m venv .env
+   source .env/bin/activate
+   pip install -r requirements.txt
 
 When refactoring or adding new features, run tests locally with:
 
-.. code-block:: bash
+.. code:: bash
 
-    pytest .
-    
-Also, use pylint and mypy for linting code:
+   pytest .
 
-.. code-block:: bash
+Also, use ``pylint`` and ``mypy`` for linting code:
 
-    pylint .
-    mypy .
+.. code:: bash
 
-Pylint should score your code 10/10 and mypy should find no issues.
+   pylint .
+   mypy .
 
-Additionally, for formatting code, you can use isort and black:
+Pylint should score your code 10/10 and mypy should find no issues.
 
-.. code-block:: bash
+Additionally, for formatting code, you can use ``isort`` and ``black``:
 
-    black .
-    isort .
+.. code:: bash
 
+   black .
+   isort .
 
-Docs
-----
-The ``docs/`` directory contains all source files for generating these documentation
-pages.
+******
+ Docs
+******
 
+The ``docs/`` directory contains all source files for generating these
+documentation pages.
 
 Development environment
-^^^^^^^^^^^^^^^^^^^^^^^
-Please setup your development environment with venv for python 3.11 as follows
+=======================
 
+Please setup your development environment with ``venv`` for python 3.11 as
+follows
 
-.. code-block:: bash
+.. code:: bash
 
-    cd docs/
-    python -m venv .env
-    source .env/bin/activate
-    pip install -r requirements.txt
-    
+   cd docs/
+   python -m venv .env
+   source .env/bin/activate
+   pip install -r requirements.txt
 
-Once your venv is ready, you can lint your pages after adding new content as follows:
+Once your ``venv`` is ready, you can lint your pages after adding new
+content as follows:
 
-.. code-block:: bash
+.. code:: bash
 
-    rstcheck -r source/
-    
-If your docs sources are right, you should find an output like the following:
-``Success! No issues detected.``
+   rstcheck -r source/
 
+If your docs sources are right, you should find an output like the
+following: ``Success! No issues detected.``
 
 Also, you can locally build doc pages with:
 
-.. code-block:: bash
+.. code:: bash
 
    make html
-
    
-Notebooks
----------
 
 
-For setting up a local jupyter notebook, run the following (inside your venv):
+Besides, if you want to apply formatting to your docs, you can use
+``rstfmt``:
+
+.. code:: bash
+
+   rstfmt -r source/
+
+***********
+ Notebooks
+***********
+
+For setting up a local jupyter notebook, run the following (inside your
+venv):
+
+.. code:: bash
 
-.. code-block:: bash
+   python -m ipykernel install --user --name=seg_tgce_env
 
-    python -m ipykernel install --user --name=seg_tgce_env
-    
-Then, open your preference tool (jupyter lab, vscode viewer, etc) 
-and select the created kernel.
+Then, open your preference tool (jupyter lab, vscode viewer, etc) and
+select the created kernel.
diff --git a/docs/source/elements/cnn.rst b/docs/source/elements/cnn.rst
@@ -1,9 +1,8 @@
-Convolutional neural networks
------------------------------
+###############################
+ Convolutional neural networks
+###############################
 
-
-
-Convolutional neural networks (CNNs) are the current state-of-the-art model 
-architecture for image classification tasks. CNNs apply a series of filters to 
-the raw pixel data of an image to extract and learn higher-level features, 
-which the model can then use for classification.
+Convolutional neural networks (CNNs) are the current state-of-the-art
+model architecture for image classification tasks. CNNs apply a series
+of filters to the raw pixel data of an image to extract and learn
+higher-level features, which the model can then use for classification.
diff --git a/docs/source/elements/loss.rst b/docs/source/elements/loss.rst
@@ -1,61 +1,59 @@
-Loss for multiple annotators segmentation
-=========================================
+###########################################
+ Loss for multiple annotators segmentation
+###########################################
 
+In general, a loss function in the context of machine learning is a
+measure of how well a model is able to predict the expected outcome.
 
-In general, a loss function in the context of machine learning is a measure of how well 
-a model is able to predict the expected outcome. 
+In the context of image segmentation, the expected outcome is a binary
+mask that indicates the location of the object of interest in the image.
+The loss function is used to compare the predicted mask with the ground
+truth mask and calculate a measure of how well the predicted mask
+matches the ground truth mask.
 
-In the context of image segmentation, the expected outcome is a binary mask 
-that indicates the location of the object of interest in the image. 
-The loss function is used to compare the predicted mask with the ground truth 
-mask and calculate a measure of how well the predicted mask matches the 
-ground truth mask.
+*******************************************************
+ Truncated segmentation generalized cross entropy loss
+*******************************************************
 
-
-Truncated segmentation generalized cross entropy loss
------------------------------------------------------
-
-
-
-Given a $k$ class multiple annotators segmentation problem with a dataset like the following'
+Given a :math:`k` class multiple annotators segmentation problem with a
+dataset like the following'
 
 .. math::
 
-    \mathbf X \in \mathbb{R}^{W \times H}, \{ \mathbf Y_r \in \{0,1\}^{W \times H \times K} \}_{r=1}^R; \;\; \mathbf {\hat Y} \in [0,1]^{W\times H \times K} = f(\mathbf X)
+   \mathbf X \in \mathbb{R}^{W \times H}, \{ \mathbf Y_r \in \{0,1\}^{W \times H \times K} \}_{r=1}^R; \;\;
+   \mathbf {\hat Y} \in [0,1]^{W\times H \times K} = f(\mathbf X)
 
 The segmentation mask function will map input output as follows:
 
 .. math::
 
-    f: \mathbb  R ^{W\times H} \to [0,1]^{W\times H\times K}
-
+   f: \mathbb  R ^{W\times H} \to [0,1]^{W\times H\times K}
 
-$\mathbf Y$ will satisfy the following condition for being a softmax-like representation:
+:math:`\mathbf Y` will satisfy the following condition for being a
+softmax-like representation:
 
 .. math::
 
-    \mathbf Y_r[w,h,:] \mathbf{1} ^ \top _ k = 1; \;\; w \in W, h \in H
-
-Now, let's suppose the existence of an annotators reliability map estimation $\Lambda_r; \; r \in R$;
+   \mathbf Y_r[w,h,:] \mathbf{1} ^ \top _ k = 1; \;\; w \in W, h \in H
 
+Now, let's suppose the existence of an annotators reliability map
+estimation :math:`\Lambda_r; \; r \in R`;
 
 .. math::
 
-    \bigg\{ \Lambda_r (\mathbf X; \theta ) \in [0,1] ^{W\times H} \bigg\}_{r=1}^R
-
-Then, our $TGCE_{SS}$:
+   \bigg\{ \Lambda_r (\mathbf X; \theta ) \in [0,1] ^{W\times H} \bigg\}_{r=1}^R
 
+Then, our :math:`TGCE_{SS}`:
 
 .. math::
 
-    TGCE_{SS}(\mathbf{Y}_r,f(\mathbf X;\theta) | \mathbf{\Lambda}_r (\mathbf X;\theta)) =\mathbb E_{r} \left\{ \mathbb E_{w,h} \left\{ \Lambda_r (\mathbf X; \theta) \circ \mathbb E_k \bigg\{    \mathbf Y_r \circ \bigg( \frac{\mathbf 1 _{W\times H \times K} - f(\mathbf X;\theta) ^{\circ q }}{q} \bigg); k \in K  \bigg\}  + \\ \left(\mathbf 1 _{W \times H } - \Lambda _r (\mathbf X;\theta)\right) \circ \bigg(   \frac{\mathbf 1_{W\times H} - (\frac {1}{k} \mathbf 1_{W\times H})^{\circ q}}{q} \bigg); w \in W, h \in H \right\};r\in R\right\} 
+   TGCE_{SS}(\mathbf{Y}_r,f(\mathbf X;\theta) | \mathbf{\Lambda}_r (\mathbf X;\theta)) =\mathbb E_{r} \left\{ \mathbb E_{w,h} \left\{ \Lambda_r (\mathbf X; \theta) \circ \mathbb E_k \bigg\{    \mathbf Y_r \circ \bigg( \frac{\mathbf 1 _{W\times H \times K} - f(\mathbf X;\theta) ^{\circ q }}{q} \bigg); k \in K  \bigg\}
+   + \left(\mathbf 1 _{W \times H } - \Lambda _r (\mathbf X;\theta)\right) \circ \bigg(   \frac{\mathbf 1_{W\times H} - (\frac {1}{k} \mathbf 1_{W\times H})^{\circ q}}{q} \bigg); w \in W, h \in H \right\};r\in R\right\}
 
+Where :math:`q \in (0,1)`
 
-Where $q \in (0,1)$
-
-Total Loss for a given batch holding $N$ samples:
+Total Loss for a given batch holding :math:`N` samples:
 
 .. math::
 
-    \mathscr{L}\left(\mathbf{Y}_r[n],f(\mathbf X[n];\theta) | \mathbf{\Lambda}_r (\mathbf X[n];\theta)\right)  = \frac{1}{N} \sum_{n}^NTGCE_{SS}(\mathbf{Y}_r[n],f(\mathbf X[n];\theta) | \mathbf{\Lambda}_r (\mathbf X[n];\theta))
-
+   \mathscr{L}\left(\mathbf{Y}_r[n],f(\mathbf X[n];\theta) | \mathbf{\Lambda}_r (\mathbf X[n];\theta)\right)  = \frac{1}{N} \sum_{n}^NTGCE_{SS}(\mathbf{Y}_r[n],f(\mathbf X[n];\theta) | \mathbf{\Lambda}_r (\mathbf X[n];\theta))
diff --git a/docs/source/experiments.rst b/docs/source/experiments.rst
@@ -1,48 +1,53 @@
-Experimental setup
-------------------
-
-We established several experiments for training and benchmarking our models,
-including the Oxford pet experiment and the histology images experiment.
-
-
-Oxford III Pet
-==============
-
-Our first experiment was elaborated on the Oxford-IIIT Pet Dataset. 
-This dataset contains 37 classes of pets, with around 200 images per class. 
-The dataset is divided into a training set and a test set. 
-The training set contains 3680 images, and the test set contains 3669 images. 
-The images are of different sizes and aspect ratios. 
-The dataset is available at the following link: 
+####################
+ Experimental setup
+####################
+
+We established several experiments for training and benchmarking our
+models, including the Oxford pet experiment and the histology images
+experiment.
+
+****************
+ Oxford III Pet
+****************
+
+Our first experiment was elaborated on the Oxford-IIIT Pet Dataset. This
+dataset contains 37 classes of pets, with around 200 images per class.
+The dataset is divided into a training set and a test set. The training
+set contains 3680 images, and the test set contains 3669 images. The
+images are of different sizes and aspect ratios. The dataset is
+available at the following link:
 https://www.robots.ox.ac.uk/~vgg/data/pets/
 
-In particular, we used an implementation of this dataset in a simplified and 
-easily retriable format, available at the following link:
+In particular, we used an implementation of this dataset in a simplified
+and easily retriable format, available at the following link:
 
 https://github.com/UN-GCPDS/python-gcpds.image_segmentation
 
+*******************
+ Scorers emulation
+*******************
 
-Scorers emulation
-=================
-
-On itself, the Oxford-IIIT Pet dataset contains the masks which reffer to the
-ground truth and not to labels from different annotators, which makes this 
-dataset non suitable for the original intention of the project. However, we
-used this dataset to emulate the scorers' behavior, by training previously a model 
-with a simple UNet architecture and then using this model to predict for being 
-disturbed in the last encoder layer for producing scorers with different lebels of
-agreement.
+On itself, the Oxford-IIIT Pet dataset contains the masks which reffer
+to the ground truth and not to labels from different annotators, which
+makes this dataset non suitable for the original intention of the
+project. However, we used this dataset to emulate the scorers' behavior,
+by training previously a model with a simple UNet architecture and then
+using this model to predict for being disturbed in the last encoder
+layer for producing scorers with different lebels of agreement.
 
 .. image:: resources/oxford_pet_scorers_emulation.png
-  :width: 100%
-  :align: center
-  :alt: How the scorers emulated noisy annotatiosn for the Oxford-IIIT Pet dataset look.
+   :width: 100%
+   :align: center
+   :alt: How the scorers emulated noisy annotatiosn for the Oxford-IIIT Pet dataset look.
 
-Crowd Seg Histopatological images
-=================================
+***********************************
+ Crowd Seg Histopatological images
+***********************************
 
-Our second experiment was elaborated on the CrowdSeg dataset, which consists of 
-Triple Negative Breast Cancer images labeled by 20 medical students.
+Our second experiment was elaborated on the CrowdSeg dataset, which
+consists of Triple Negative Breast Cancer images labeled by 20 medical
+students.
 
-This dataset fairly represents the original intention of the project, which is to
-provide a tool for pathologists to segment histopathological images.
+This dataset fairly represents the original intention of the project,
+which is to provide a tool for pathologists to segment histopathological
+images.