From 6680f64e50ae6867803d341e5eb15a9fe6b58dfe Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Thu, 20 Mar 2025 11:22:55 +0100 Subject: [PATCH] Implemented draft for py yml and optimized assets urls --- sphinx/Makefile | 13 +++++++++++-- sphinx/README.md | 33 +++++++++++++++++++++++++++++++-- sphinx/conf.py | 32 ++++++++++++++++++++++++++++++++ sphinx/requirements.txt | 3 ++- sphinx/templates/logo.html | 2 +- 5 files changed, 77 insertions(+), 6 deletions(-) diff --git a/sphinx/Makefile b/sphinx/Makefile index c9601e22..6e06da27 100644 --- a/sphinx/Makefile +++ b/sphinx/Makefile @@ -7,17 +7,26 @@ SPHINXBUILD ?= sphinx-build SPHINX_SOURCE_DIR ?= ../ SPHINX_BUILD_DIR ?= ../docs -.PHONY: help install copy-images Makefile +.PHONY: help install copy-images apidoc html Makefile # Copy images before running any Sphinx command (except for help) copy-images: - @echo "Copying images from ../images/ to ./assets/img/..." + @echo "Copying images from ../assets/img/ to ./assets/img/..." cp -r ../assets/img/* ./assets/img/ +# Generate reStructuredText files from Python modules using sphinx-apidoc +apidoc: + @echo "Running sphinx-apidoc..." + sphinx-apidoc -f -o $(SPHINX_SOURCE_DIR)/modules $(SPHINX_SOURCE_DIR) + # "help" target does not copy images help: @$(SPHINXBUILD) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) +# HTML target depends on apidoc so that sphinx-apidoc runs first +html: copy-images apidoc + @$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O) + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/sphinx/README.md b/sphinx/README.md index 04cc6c18..626feee1 100644 --- a/sphinx/README.md +++ b/sphinx/README.md @@ -1,3 +1,6 @@ +Hier die angepasste Version der README.md mit Erläuterungen zu den zusätzlichen Befehlen: + +```markdown # Documentation CyMaIS uses [Sphinx](https://www.sphinx-doc.org/) to automatically generate its documentation and leverages the [Awesome Sphinx Theme](https://sphinxawesome.xyz/) for a sleek and responsive design. Enjoy a seamless, visually engaging experience 🚀✨. @@ -18,13 +21,39 @@ To generate the documentation locally, run the following command: pkgmgr shell cymais -c "make refresh" ``` -This command cleans the previous build and generates the updated documentation. Once complete, you can view it at the output location (e.g., [templates/html/index.html](templates/html/index.html)) 👀💻. +This command performs the following steps: +- **Copy Images:** Before building, it copies the necessary image assets from `../assets/img/` to `./assets/img/` using the `copy-images` target. +- **Generate API Documentation:** It executes `sphinx-apidoc` (via the `apidoc` target) to automatically generate reStructuredText files for all Python modules. These files are stored under a designated directory (e.g., `modules`), ensuring that every Python file is included in the documentation. +- **Build HTML Documentation:** Finally, it builds the HTML documentation using `sphinx-build` (triggered by the `html` target). + +Once complete, you can view the documentation at the output location (e.g., [templates/html/index.html](templates/html/index.html)) 👀💻. #### On Server +The same commands can be used on the server to ensure that documentation is always up to date. Make sure the server environment is properly configured with the necessary Python packages and assets. + +### Additional Commands + +- **`make copy-images`:** + Copies image files from the assets directory into the local documentation directory. This ensures that all required images are available for the generated documentation. + +- **`make apidoc`:** + Runs `sphinx-apidoc` to scan all Python files in the source directory and generate corresponding reStructuredText files. This automates the inclusion of all Python modules into the Sphinx documentation. + +- **`make html`:** + This target depends on the `apidoc` target. It first generates the API documentation and then builds the HTML documentation using `sphinx-build`. This is the standard target to produce the final, viewable documentation. + +- **`make refresh`:** + A custom target (typically defined as a combination of cleaning the previous build and then running `make html`) that ensures the documentation is regenerated from scratch with the latest changes. ### Debug -To debug and produce an .log execute: + +To debug and produce a log file, execute: + ```bash pkgmgr shell cymais -c "make refresh SPHINXOPTS='-v -c .' 2>&1 | tee debug.log" +``` + +This command increases the verbosity of the Sphinx build process and redirects all output to `debug.log`, which is useful for troubleshooting any issues during the documentation build. + ``` \ No newline at end of file diff --git a/sphinx/conf.py b/sphinx/conf.py index 63c60dea..8d810b99 100644 --- a/sphinx/conf.py +++ b/sphinx/conf.py @@ -16,6 +16,13 @@ project = 'CyMaIS - Cyber Master Infrastructure Solution' copyright = '2025, Kevin Veen-Birkenbach' author = 'Kevin Veen-Birkenbach' +# Highlighting for Jinja +from sphinx.highlighting import lexers +from pygments.lexers.templates import DjangoLexer + +lexers['jinja'] = DjangoLexer() +lexers['j2'] = DjangoLexer() + # -- General configuration --------------------------------------------------- templates_path = ['templates'] exclude_patterns = ['docs', 'venv', 'venv/**'] @@ -54,6 +61,9 @@ extensions = [ 'extensions.local_subfolders', 'extensions.roles_overview', 'extensions.markdown_include', + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', # Optional, wenn Sie Google- oder NumPy-Dokstrings verwenden + ] autosummary_generate = True @@ -62,7 +72,29 @@ myst_enable_extensions = [ "colon_fence", ] +import logging +from docutils import nodes + +logger = logging.getLogger(__name__) + +def replace_assets_in_doctree(app, doctree, docname): + # Replace asset references in image nodes + for node in doctree.traverse(nodes.image): + if "assets/" in node['uri']: + new_uri = node['uri'].replace("assets/", "_static/") + node['uri'] = new_uri + logger.info("Replaced image URI in {}: {}".format(docname, new_uri)) + + # Replace asset references in raw HTML nodes + for node in doctree.traverse(nodes.raw): + if node.get('format') == 'html' and "assets/" in node.astext(): + new_text = node.astext().replace("assets/", "_static/") + node.children = [nodes.raw('', new_text, format='html')] + logger.info("Replaced raw HTML assets in {}.".format(docname)) + def setup(app): + app.connect("doctree-resolved", replace_assets_in_doctree) + python_domain = app.registry.domains.get('py') if python_domain is not None: directive = python_domain.directives.get('currentmodule') diff --git a/sphinx/requirements.txt b/sphinx/requirements.txt index 9f2567d2..6945d242 100644 --- a/sphinx/requirements.txt +++ b/sphinx/requirements.txt @@ -1,4 +1,5 @@ myst-parser sphinx sphinxawesome-theme -docutils \ No newline at end of file +docutils +sphinxcontrib-jinja \ No newline at end of file diff --git a/sphinx/templates/logo.html b/sphinx/templates/logo.html index 45857305..c4d41ebf 100644 --- a/sphinx/templates/logo.html +++ b/sphinx/templates/logo.html @@ -1,5 +1,5 @@