From 76932db6b1a05592f9f8ad4b2ee1bd75f5adad37 Mon Sep 17 00:00:00 2001
From: Brandon Lotero <blotero@gmail.com>
Date: Wed, 13 Dec 2023 15:33:19 -0500
Subject: [PATCH] docs\feat: #20 docs linting

- added docs linting utils
- included contribution section in docs
---
 docs/requirements.txt        | 13 +++++++
 docs/source/conf.py          | 21 ++++++-----
 docs/source/contribution.rst | 71 ++++++++++++++++++++++++++++++++++++
 docs/source/index.rst        |  3 +-
 4 files changed, 97 insertions(+), 11 deletions(-)
 create mode 100644 docs/source/contribution.rst

diff --git a/docs/requirements.txt b/docs/requirements.txt
index e1bb1af..67d29ef 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,15 +1,26 @@
 alabaster==0.7.13
+annotated-types==0.6.0
 Babel==2.13.1
 certifi==2023.11.17
 charset-normalizer==3.3.2
+click==8.1.7
+colorama==0.4.6
 docutils==0.20.1
 idna==3.6
 imagesize==1.4.1
 Jinja2==3.1.2
+markdown-it-py==3.0.0
 MarkupSafe==2.1.3
+mdurl==0.1.2
 packaging==23.2
+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
+shellingham==1.5.4
 snowballstemmer==2.2.0
 Sphinx==7.2.6
 sphinx-wagtail-theme==6.1.1
@@ -19,4 +30,6 @@ sphinxcontrib-htmlhelp==2.0.4
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.6
 sphinxcontrib-serializinghtml==1.1.9
+typer==0.9.0
+typing_extensions==4.9.0
 urllib3==2.1.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
index fc6a1f4..baa9160 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -6,18 +6,18 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'semantic-segmentation-tgce'
-copyright = '2023, Brandon Lotero'
-author = 'Brandon Lotero'
+project = "semantic-segmentation-tgce"
+copyright = "2023, Brandon Lotero"
+author = "Brandon Lotero"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx_wagtail_theme']
-
-templates_path = ['_templates']
-exclude_patterns = []
+extensions = [
+    "sphinx_wagtail_theme", 
+]
 
+templates_path = ["_templates"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -25,6 +25,9 @@
 # include the theme in the list of extensions to be loaded
 
 # select the theme
-html_theme = 'sphinx_wagtail_theme'
+html_theme = "sphinx_wagtail_theme"
+
+html_static_path = ["_static"]
+
+highlight_language = 'bash'
 
-html_static_path = ['_static']
diff --git a/docs/source/contribution.rst b/docs/source/contribution.rst
new file mode 100644
index 0000000..b600cea
--- /dev/null
+++ b/docs/source/contribution.rst
@@ -0,0 +1,71 @@
+Contribution
+============
+
+
+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:
+
+.. code-block:: bash
+
+    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
+
+    pytest .
+    
+Also, use pylint and mypy for linting code:
+
+.. code-block:: bash
+
+    pylint src/
+    mypy src/
+
+Pylint should score your code 10/10 and mypy should find no issues.
+
+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
+
+
+.. code-block:: bash
+
+    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:
+
+.. code-block:: bash
+
+    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
+
+   make html
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 44795a8..72e48b9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -8,9 +8,8 @@ Semantic Segmentation TCGE Framework
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
 
+   contribution
 
 Indices and tables
 ==================