Implemented more auto docs

.gitignore

@@ -1,5 +1,4 @@
 site.retry
 *__pycache__
 venv
-*.log
-modules/*
+*.log

08_DEVELOPE.md

@@ -1 +0,0 @@
-# Developer Guide

08_DEVELOPE.rst

@@ -0,0 +1,4 @@
+Developer Guide 
+===============
+
+:doc: docs/generated/yaml_index.rst

docs/.gitignore

@@ -1,2 +1,4 @@
 assets/img/*
-generated/*
+build/*
+generated/*
+!generated/.gitkeep

docs/Makefile

@@ -5,10 +5,10 @@
 SPHINXOPTS         		?=	-c .
 SPHINXBUILD        		?=	sphinx-build
 SPHINX_SOURCE_DIR  		?=	../
-SPHINX_BUILD_DIR   		?=	./generated
-SPHINX_APIDOC_BUILD_DIR =	$(SPHINX_SOURCE_DIR)modules	 
+SPHINX_BUILD_DIR   		?=	./build
+SPHINX_GENERATED_DIR 	=	./generated
 
-.PHONY: help install copy-images apidoc remove-apidoc html Makefile
+.PHONY: help install copy-images apidoc remove-generated html Makefile
 
 # Copy images before running any Sphinx command (except for help)
 copy-images:
@@ -16,23 +16,31 @@ copy-images:
 	cp -vr ../assets/img/* ./assets/img/
 
 # Generate reStructuredText files from Python modules using sphinx-apidoc
-apidoc:
+generate-apidoc:
 	@echo "Running sphinx-apidoc..."
-	sphinx-apidoc -f -o $(SPHINX_APIDOC_BUILD_DIR) $(SPHINX_SOURCE_DIR)
+	sphinx-apidoc -f -o $(SPHINX_GENERATED_DIR)/modules $(SPHINX_SOURCE_DIR)
 
-remove-apidoc:
-	@echo "Removing sphinx-apidoc files..."
-	- rm -rv $(SPHINX_APIDOC_BUILD_DIR)
+remove-generated:
+	@echo "Removing generated files..."
+	- find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete
+
+generate-yaml-index:
+	@echo "Generating YAML index..."
+	python generators/yaml_index.py --source-dir $(SPHINX_SOURCE_DIR) --output-file $(SPHINX_GENERATED_DIR)/yaml_index.rst
+
+generate-ansible-roles:
+	@echo "Generating Ansible roles documentation..."
+	python generators/ansible_roles.py --roles-dir $(SPHINX_SOURCE_DIR)/roles --output-dir $(SPHINX_GENERATED_DIR)/roles
 
 # "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
-	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
+html: copy-images generate-apidoc generate-yaml-index generate-ansible-roles
+	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)
 
-clean: remove-apidoc
+
+clean: remove-generated
 	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/conf.py

@@ -25,7 +25,11 @@ lexers['j2'] = DjangoLexer()
 
 # -- General configuration ---------------------------------------------------
 templates_path = ['templates']
-exclude_patterns = ['docs', 'venv', 'venv/**']
+exclude_patterns = [
+    'docs/build', 
+    'venv', 
+    'venv/**'
+    ]
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinxawesome_theme'
@@ -50,6 +54,8 @@ html_theme_options = {
 source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',
+    '.yml': 'restructuredtext',
+    '.yaml': 'restructuredtext',
 }
 
 sys.path.insert(0, os.path.abspath('./extensions'))
@@ -62,8 +68,7 @@ extensions = [
     'extensions.roles_overview',
     'extensions.markdown_include',
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',  # Optional, wenn Sie Google- oder NumPy-Dokstrings verwenden
-
+    'sphinx.ext.napoleon',
 ]
 
 autosummary_generate = True

docs/generators/ansible_roles.py

@@ -0,0 +1,42 @@
+import os
+import yaml
+import argparse
+
+def generate_ansible_roles_doc(roles_dir, output_dir):
+    """Generates reStructuredText documentation for Ansible roles."""
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    for role in os.listdir(roles_dir):
+        role_path = os.path.join(roles_dir, role)
+        meta_file = os.path.join(role_path, "meta/main.yml")
+        readme_file = os.path.join(role_path, "README.md")
+
+        if os.path.exists(meta_file):
+            with open(meta_file, "r", encoding="utf-8") as f:
+                meta_data = yaml.safe_load(f)
+
+            role_doc = os.path.join(output_dir, f"{role}.rst")
+            with open(role_doc, "w", encoding="utf-8") as f:
+                f.write(f"{role.capitalize()} Role\n")
+                f.write("=" * (len(role) + 7) + "\n\n")
+                f.write(f"**Description:** {meta_data.get('description', 'No description available')}\n\n")
+
+                f.write("### Variables\n")
+                for key, value in meta_data.get('galaxy_info', {}).items():
+                    f.write(f"- **{key}**: {value}\n")
+
+                if os.path.exists(readme_file):
+                    f.write("\n### README\n")
+                    with open(readme_file, "r", encoding="utf-8") as readme:
+                        f.write("\n" + readme.read())
+
+    print(f"Ansible roles documentation has been generated in {output_dir}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Generate documentation for Ansible roles.")
+    parser.add_argument("--roles-dir", required=True, help="Directory containing Ansible roles.")
+    parser.add_argument("--output-dir", required=True, help="Directory where documentation will be saved.")
+
+    args = parser.parse_args()
+    generate_ansible_roles_doc(args.roles_dir, args.output_dir)

docs/generators/yaml_index.py

@@ -0,0 +1,49 @@
+import os
+import argparse
+import pathspec
+
+def load_gitignore_patterns(source_dir):
+    """Loads .gitignore patterns from the given source directory and returns a PathSpec object."""
+    gitignore_path = os.path.join(source_dir, ".gitignore")
+    if not os.path.exists(gitignore_path):
+        return pathspec.PathSpec.from_lines("gitwildmatch", [])
+
+    with open(gitignore_path, "r", encoding="utf-8") as f:
+        patterns = f.readlines()
+    
+    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
+
+def generate_yaml_index(source_dir, output_file):
+    """Generates an index file listing all YAML files in the specified directory while respecting .gitignore rules."""
+    
+    yaml_files = []
+    spec = load_gitignore_patterns(source_dir)  # Load .gitignore rules
+    
+    # Walk through the source directory and collect YAML files
+    for root, _, files in os.walk(source_dir):
+        for file in files:
+            file_path = os.path.relpath(os.path.join(root, file), start=source_dir)
+
+            if file.endswith(('.yml', '.yaml')) and not spec.match_file(file_path):
+                yaml_files.append(os.path.join(root, file))
+    
+    # Create the output directory if it doesn't exist
+    os.makedirs(os.path.dirname(output_file), exist_ok=True)
+
+    # Write the YAML index to the output file
+    with open(output_file, "w", encoding="utf-8") as f:
+        f.write("YAML Files\n===========\n\n")
+        f.write("This document lists all `.yaml` and `.yml` files found in the specified directory, excluding ignored files.\n\n")
+
+        for file in sorted(yaml_files):
+            f.write(f".. literalinclude:: {file}\n   :language: yaml\n   :linenos:\n\n")
+
+    print(f"YAML index has been generated at {output_file}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Generate an index for YAML files while respecting .gitignore.")
+    parser.add_argument("--source-dir", required=True, help="Directory containing YAML files.")
+    parser.add_argument("--output-file", required=True, help="Path to the output .rst file.")
+
+    args = parser.parse_args()
+    generate_yaml_index(args.source_dir, args.output_file)

docs/requirements.txt

@@ -2,4 +2,6 @@ myst-parser
 sphinx
 sphinxawesome-theme
 docutils
-sphinxcontrib-jinja
+sphinx-jinja
+sphinxcontrib-yaml
+pathspec

index.rst

@@ -1,4 +1,4 @@
 About
 ===============================
 
-.. markdown-include:: README.md
+.. markdown-include:: ../README.md

roles/docker-jenkins/README.md

@@ -1 +1,2 @@
+# Jenkins
 This role is deprecated. Needs to be reimplemented.

roles/docker-xmpp/README.md

@@ -1,3 +1,5 @@
+# XMPP
+This role needs to be implemented
 - https://hub.docker.com/r/ejabberd/ecs/
 - https://docs.ejabberd.im/CONTAINER/
 - https://github.com/processone/docker-ejabberd

roles/nginx-https/README.md

@@ -1 +1,2 @@
+# Nginx Https Server
 This role loads the components to create an nginx server with https