Redrafted Sphinx for CyMaIS

docs/.gitignore

@@ -1,5 +1,8 @@
 assets/img/*
 !assets/img/.gitkeep
-build/*
+output/*
+!output/.gitkeep
 generated/*
-!generated/.gitkeep
+!generated/.gitkeep
+requirements/*
+!requirements/.gitkeep

docs/Dockerfile

@@ -0,0 +1,37 @@
+ARG DOCKER_PYTHON_VERSION
+FROM python:${DOCKER_PYTHON_VERSION}
+
+ARG SPHINX_SOURCE_DIR
+ARG SPHINX_OUTPUT_DIR
+ARG SPHINX_EXEC_DIR
+ARG SPHINX_DOCKER_EXEC_DIR
+ARG SPHINX_SOURCE_DIR_RELATIVE
+
+# Set the environment variables so they are available during build for Makefile
+ENV SPHINX_SOURCE_DIR=${SPHINX_SOURCE_DIR}
+ENV SPHINX_OUTPUT_DIR=${SPHINX_OUTPUT_DIR}
+ENV SPHINX_REQUIREMENTS_DIR=${SPHINX_EXEC_DIR}/requirements
+
+# Build the requirement files
+RUN cd ${SPHINX_EXEC_DIR} && make requirements
+
+# Install required packages
+RUN apt-get update && xargs -a ${SPHINX_REQUIREMENTS_DIR}/apt.txt apt install -y
+
+# Set the working directory
+WORKDIR ${SPHINX_DOCKER_EXEC_DIR}
+
+# Copy the project files into the container
+COPY ${SPHINX_SOURCE_DIR_RELATIVE} ${SPHINX_DOCKER_EXEC_DIR}
+
+# Install Python packages via requirements.txt
+RUN pip install --upgrade pip && pip install -r ${SPHINX_REQUIREMENTS_DIR}/pip.txt
+
+# Build the HTML documentation using Sphinx with the defined directories
+RUN cd ${SPHINX_EXEC_DIR} && make html
+
+# Expose port 8000 where the HTTP server will run
+EXPOSE 8000
+
+# Start a simple HTTP server to serve the built documentation
+CMD python -m http.server 8000 --directory "${SPHINX_OUTPUT_DIR}html/"

docs/Makefile

@@ -1,14 +1,33 @@
-# Minimal Makefile for Sphinx documentation
-#
-# You can set these variables from the command line, and also
-# from the environment
-SPHINXOPTS         		?=	-c .
-SPHINXBUILD        		?=	sphinx-build
-SPHINX_SOURCE_DIR  		?=	../
-SPHINX_BUILD_DIR   		?=	./build
-SPHINX_GENERATED_DIR 	=	$(SPHINX_BUILD_DIR)/../generated
+# PARAMETER (with default values)
 
-.PHONY: help install copy-images apidoc remove-generated html generate Makefile
+# Directory which cointains the Makefile
+SPHINX_EXEC_DIR			?= .
+
+# Directory from which the sources will be read
+SPHINX_SOURCE_DIR  		?= ../
+
+# Directory which contains the builded files
+SPHINX_OUTPUT_DIR   	?= ./output
+
+# Args parsed to the sphinx-build command
+SPHINXOPTS         		?= -c $(SPHINX_EXEC_DIR)
+
+# CONSTANTS
+
+# Sphinx build command
+SPHINX_BUILD_COMMAND    = sphinx-build
+
+# Directory which contains the auto generated files
+SPHINX_GENERATED_DIR 	= $(SPHINX_OUTPUT_DIR)/../generated
+
+# Directory which contains the extracted requirement files
+SPHINX_REQUIREMENTS_DIR = $(SPHINX_EXEC_DIR)/requirements
+
+.PHONY: help install copy-images apidoc remove-generated html generate extract-requirements Makefile
+
+extract-requirements:
+	@echo "Creating requirement files"
+	bash ./scripts/extract-requirements.sh "$(SPHINX_EXEC_DIR)/requirements.yml" "$(SPHINX_REQUIREMENTS_DIR)/apt.txt" "$(SPHINX_REQUIREMENTS_DIR)/pip.txt"
 
 # Copy images before running any Sphinx command (except for help)
 copy-images:
@@ -42,20 +61,20 @@ remove-generated:
 	- find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete
 
 help:
-	@$(SPHINXBUILD) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINX_BUILD_COMMAND) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) $(O)
 
 html: copy-images generate
 	@echo "Building Sphinx documentation..."
-	$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)
+	$(SPHINX_BUILD_COMMAND) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS)
 
 just-html:
-	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)
+	@$(SPHINX_BUILD_COMMAND) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS)
 
 
 clean: remove-generated
-	@$(SPHINXBUILD) -M clean "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINX_BUILD_COMMAND) -M clean "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_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
-	@$(SPHINXBUILD) -M $@ "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINX_BUILD_COMMAND) -M $@ "$(SPHINX_SOURCE_DIR)" "$(SPHINX_OUTPUT_DIR)" $(SPHINXOPTS) $(O)

docs/generators/ansible_roles.py

@@ -15,7 +15,7 @@ def convert_md_to_rst(md_content):
         return result.stdout.decode("utf-8")
     except subprocess.CalledProcessError as e:
         print("Error converting Markdown to reStructuredText:", e)
-        return md_content  # Falls Pandoc fehlschlägt, nutze das Original als Fallback
+        return md_content
 
 def generate_ansible_roles_doc(roles_dir, output_dir):
     """Generates reStructuredText documentation for Ansible roles."""

docs/requirements.txt

@@ -1,9 +0,0 @@
-myst-parser
-sphinx
-sphinxawesome-theme
-docutils
-sphinx-jinja
-sphinxcontrib-yaml
-pathspec
-markdown2
-pandoc

docs/requirements.yml

@@ -0,0 +1,13 @@
+apt:
+  make
+  curl
+  pandoc
+pip:
+  myst-parser
+  sphinx
+  sphinxawesome-theme
+  docutils
+  sphinx-jinja
+  sphinxcontrib-yaml
+  pathspec
+  markdown2

docs/scripts/extract-requirements.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Check if correct number of arguments is given
+if [[ $# -ne 3 ]]; then
+  echo "Usage: $0 <input_file> <apt_output_file> <pip_output_file>"
+  echo "Input: $0 <$1> <$2> <$3>"
+  exit 1
+fi
+
+input_file="$1"
+apt_file="$2"
+pip_file="$3"
+
+# Clear the output files
+> "$apt_file"
+> "$pip_file"
+
+current_section=""
+
+while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+
+  if [[ "$line" == apt:* ]]; then
+    current_section="apt"
+    continue
+  elif [[ "$line" == pip:* ]]; then
+    current_section="pip"
+    continue
+  fi
+
+  package=$(echo "$line" | sed 's/^[[:space:]]*//')
+
+  if [[ "$current_section" == "apt" ]]; then
+    echo "$package" >> "$apt_file"
+  elif [[ "$current_section" == "pip" ]]; then
+    echo "$package" >> "$pip_file"
+  fi
+done < "$input_file"