Updated documentation's docs

colvert-project · Oct 23, 2024 · 0aae2e3 · 0aae2e3
1 parent cd24a47
commit 0aae2e3
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 14 deletions.
diff --git a/docs/General.md b/docs/General.md
@@ -19,12 +19,19 @@ No problem with files state.
 
 ### Documentation Build
 
-It uses **Sphinx** with a third-party GitHub workflow in `.github/workflows/build-docs.yml`
+It uses **Sphinx** with a third-party GitHub workflow in `.github/workflows/build-docs.yml` to trigger build on `git push` action. It uses the third-party action [`sphinx-notes/pages@v3`](https://github.com/sphinx-notes/pages).
 
-|`docs/conf.py`|https://www.sphinx-doc.org/en/master/usage/configuration.html|
-|`docs/requirements.txt`|pip packages needed by Sphinx|
+|File                   |Usage                                                                                                                    |
+|-----------------------|-------------------------------------------------------------------------------------------------------------------------|
+|`static/`              |Classic favicon, logo, and other static file to serve.                                                                   |
+|`docs/requirements.txt`|pip packages needed by Sphinx to build documentation. Commented.                                                         |
+|`docs/conf.py`         |Sphinx configuration. Commented.                                                                                         |
+|`CNAME`                |Define the base URL for documentation. Not used by GitHub as built using a workflow, but used by `conf.py`.              |
+|`index.rst.j2`         |Jinja2 parsed first template (`conf.py`) to load docs from connectors, then Sphinx index using *reStructuredText* format.|
+|`*.md`                 |All others documentation files in Markdown format.                                                                       |
 
-_TODO_ - To Finish
+Help links:
+* Sphinx docs for `conf.py`: <https://www.sphinx-doc.org/en/master/usage/configuration.html>
 
 # Architecture
 
@@ -36,8 +43,6 @@ AdminLTE
 
 **Colvert** is a web application written in **_Python_ 3**, built on **_Django_ 5** web framework with **_AdminLTE 4_** as **_Bootstrap_ 5** template for view and control parts.
 
-
-
 ## Project Setup
 
 ### Packages Installation
@@ -57,6 +62,12 @@ pip 24.2 from /usr/local/python/3.12.1/lib/python3.12/site-packages/pip (python
  5.1.1
 ```
 
+```shell
+ /workspaces/colvert (main) $ python -m pip install WhiteNoise
+ ...
+ Successfully installed whitenoise-6.7.0
+```
+
 ### Django Project Initialization
 
 Within the root repository folder ```/workspaces/colvert```.
@@ -96,11 +107,19 @@ For future library update, run again commands above by replacing the Bootstrap /
 
 * `main` branch for now.
 
+### Docstrings
+
+**Docstrings** is done using *reStructuredText* formatting.
+
 ### Packaging & Run
 
-_TODO_ pip freeze > requirements.txt
+Update `requirements.txt`
 
 ```shell
 python manage.py migrate
 python manage.py runserver
 ```
+
+TODO - Collect staticfiles
+
+TODO - Merge migrations
diff --git a/docs/index.rst.j2 b/docs/index.rst.j2
@@ -1,14 +1,14 @@
 Welcome to Colvert's documentation!
 ===================================
 
-**Colvert** is a tool made for cybersecurity teams (CSIRTs / SOCs) and designed to manage their portfolio of _detection use cases_ through their entire lifecycle in the context of **Information Security Event Management**.
+**Colvert** is a tool made for cybersecurity teams (CSIRTs / SOCs) and designed to manage their portfolio of *detection use cases* through their entire lifecycle in the context of **Information Security Event Management**.
 
 The tool consists of:
 
-* _TODO_ - The main application
-* _TODO_ - Connectors to potentially get data from providers and more-valued information.
+* The main application.
+* Connectors to potentially get data from providers and contextual more-valued information.
 
-Go to the main repository <https://github.com/colvert-project/colvert> for an overview of the tool.
+Go to the main repository `https://github.com/colvert-project/colvert`_ for an overview of the tool.
 
 * Website: <https://colvert.io>
 * Contact: contact@colvert.io
@@ -54,7 +54,7 @@ The following section contains information intended to help developers to unders
 
 .. toctree::
    :maxdepth: 3
-   :caption: Core System PyDoc
+   :caption: Core System Docstrings
 
    _generated/modules
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Jinja2 parser
-jinja2
+Jinja2
 # Markdown parser for Sphinx
 myst-parser
-#Sphinx's Read the Docs Theme
+# Sphinx's Read the Docs Theme
 sphinx_rtd_theme