Major fix with Jinja2 to manage Index which includes connectors docs

colvert/settings.py

@@ -141,8 +141,9 @@
 APP_SUB_NAME = "The Detection Use Case Management Tool"
 APP_DESC = "Manage your detection use cases portfolio"
 APP_LONG_DESC = "Manage your portfolio of detection use cases with the possibility to document and follow-up use cases development, improvement and implementation; testing status; risk coverage compared to well-known security threats based on multiple contextual data sources; related preventive controls; and instructions for analysts triage, qualification, and correlation as playbooks and Standard Operating Procedures (SOPs)."
-APP_CONTRIBUTORS = "styx0x6 <https://github.com/styx0x6>"
-APP_SPONSOR = "Maybe you"
+APP_AUTHORS = "styx0x6 <https://github.com/styx0x6>"
+APP_CONTRIBUTORS = "The Colvert Contributors"
+APP_SPONSORS = "styx0x6 & maybe you"
 APP_LICENCE = "EUPL-1.2"
 APP_MAIL_CONTACT = "contact@colvert.io"
 APP_URL_WEBSITE = "https://colvert.io"
@@ -155,9 +156,12 @@
 APP_URL_SECURITY_ADVISORIES = "https://github.com/colvert-project/colvert/security/advisories"
 APP_CONTRIBUTING_MD = "CONTRIBUTING.md"
 APP_COC_MD = "CODE_OF_CONDUCT.md"
-APP_POWERED_BY = "Django+AdminLTE"
+APP_EMPOWERING_TECH = "Django & AdminLTE"
 APP_VERSION = "0.1.0"
 APP_YEARS = "2024"
 APP_VERSION_STRING = "%s/%s" % (APP_TECH_NAME, APP_VERSION)
 APP_COPYRIGHT_STRING = "Copyright (C) %s  %s. %s." % (APP_YEARS, APP_CONTRIBUTORS, APP_LICENCE)
 APP_COPYRIGHT_HTML = "Copyright &copy; %s %s. Licensed under the %s." % (APP_YEARS, APP_CONTRIBUTORS, APP_LICENCE)
+APP_CREATED_BY = "Created by %s" % (APP_AUTHORS)
+APP_SPONSORED_BY = "Sponsored by %s" % (APP_SPONSORS)
+APP_POWERED_BY = "Powered by %s" % (APP_EMPOWERING_TECH)

connectors/TEMP

@@ -0,0 +1 @@
+Temp file to create future connectors directory.

docs/CNAME

@@ -0,0 +1 @@
+docs.colvert.io

docs/Credits.md

@@ -0,0 +1,11 @@
+# Credits
+
+Python
+
+Django
+
+Bootstrap
+
+AdminLTE
+
+Shields.io

docs/conf.py

@@ -19,20 +19,71 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import sys
+
+colvert_docs_root_reldir = '.'
+colvert_root_reldir ='..'
+colvert_main_reldir ='../colvert'
+colvert_core_reldir ='../core'
+
+sys.path.insert(0, os.path.abspath(colvert_docs_root_reldir, colvert_main_reldir, colvert_core_reldir))
+
+# Directory name in colvert which acts as connectors repository
+COLVERT_CONNECTORS_REPO_NAME = 'connectors'
+# Directory name in connector to pull documentation from
+CONNECTOR_DOCS_DIR_NAME = 'docs'
+
+# -- Prework run -------------------------------------------------------------
+
+from shutil import copytree
+from jinja2 import Environment, FileSystemLoader
+
+# => sphinx-apidoc
+#TODO sphinx-apidoc
+
+# => Import documentation from connectors
+
+colvert_docs_connectors_abspath = os.path.abspath(os.path.join(colvert_docs_root_reldir, COLVERT_CONNECTORS_REPO_NAME))
+colvert_connectors_repo_abspath = os.path.abspath(os.path.join(colvert_root_reldir, COLVERT_CONNECTORS_REPO_NAME))
+
+# List of copied files to add to index
+connectors_docs_files = []
+
+# Copy docs directory from connectors to docs/connectors/{connector_name}/
+for f in os.scandir(colvert_connectors_repo_abspath):
+    if not f.is_dir():
+        continue
+
+    connector_docs_dir = os.path.join(f.path, CONNECTOR_DOCS_DIR_NAME)
+    if not os.path.isdir(connector_docs_dir):
+        continue
+    else:
+        colvert_docs_connector_dir = os.path.join(colvert_docs_connectors_abspath, f.name)
+        copied_path = copytree(connector_docs_dir, colvert_docs_connector_dir, dirs_exist_ok=True)
+        #TODO Manage subdir which is not the case here
+        for f in os.listdir(copied_path):
+            if f.endswith('.md') or f.endswith('.rst'):
+                connectors_docs_files.append(os.path.relpath(f, colvert_docs_root_reldir))
+
+# Create index.rst from Jinja2 template
+env = Environment(loader=FileSystemLoader(searchpath=str(colvert_docs_root_reldir)))
+index_template = env.get_template('index.rst.j2')
+index_content = index_template.render(plugin_docs=connectors_docs_files)
+
+with open(os.path.join(colvert_docs_root_reldir, 'index.rst'), 'w') as f:
+    f.write(index_content)
 
 # -- Project information -----------------------------------------------------
 
-project = 'Colvert'
-author = 'The Colvert Contributors'
-copyright = '2024-%Y, ' + author
-version = '0.1' #TODO - Get from ?
-release = '0.1.0' #TODO - Get from ?
+# Get project, author, version and release from colvert's settings.py file
 
+project = 'Colvert' #TODO - Get from APP_SHORT_NAME
+author = 'The Colvert Contributors' #TODO - Get from APP_CONTRIBUTORS
+copyright = 'TODO' #TODO - Get from '%s, %s. %s. %s. %s' % (APP_YEARS, author, APP_CREATED_BY, APP_SPONSORED_BY, APP_POWERED_BY)
+version = '0.1' #TODO - Get from APP_VERSION
+release = '0.1.0' #TODO - Get from APP_VERSION
 
 # -- General configuration ---------------------------------------------------
 
@@ -57,6 +108,7 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_title = 'Colvert Documentation'
+# Get html_baseurl from the "file variable" CNAME
 html_baseurl = 'docs.colvert.io' #TODO - Get from CNAME
 # Copy of colvert_square_192px.png
 html_logo = 'static/logo.png'

docs/index.rst.j2

@@ -18,14 +18,14 @@ The following section contains documentation from installed connectors.
    {{ connector_doc }}
 {% endfor %}
 
-The following section contains information intended to help developers
-understand the inner workings of the Colvert tool and Colvert connectors.
+The following section contains information intended to help developers understand the inner workings of the Colvert tool and Colvert connectors.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Developer Information
+   :caption: Developer Documentation
 
    General.md
+   Credits.md
 
 .. toctree::
    :maxdepth: 3

docs/requirements.txt

@@ -1,3 +1,5 @@
+# Jinja2 parser
+jinja2
 # Markdown parser for Sphinx
 myst-parser
 #Sphinx's Read the Docs Theme