From 0aae2e373f39aa58b51fd9d584db45f5fa996652 Mon Sep 17 00:00:00 2001 From: styx0x6 Date: Wed, 23 Oct 2024 21:08:12 +0000 Subject: [PATCH] Updated documentation's docs --- docs/General.md | 33 ++++++++++++++++++++++++++------- docs/index.rst.j2 | 10 +++++----- docs/requirements.txt | 4 ++-- 3 files changed, 33 insertions(+), 14 deletions(-) diff --git a/docs/General.md b/docs/General.md index 097bcb7..29c416c 100644 --- 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`: # 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 index 3aa6c4e..c1d9366 100644 --- 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 for an overview of the tool. +Go to the main repository `https://github.com/colvert-project/colvert`_ for an overview of the tool. * Website: * 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 index 3328237..d56aae8 100644 --- 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 \ No newline at end of file