Finished optimization for today

docs/Makefile

@@ -6,9 +6,9 @@ SPHINXOPTS         		?=	-c .
 SPHINXBUILD        		?=	sphinx-build
 SPHINX_SOURCE_DIR  		?=	../
 SPHINX_BUILD_DIR   		?=	./build
-SPHINX_GENERATED_DIR 	=	./generated
+SPHINX_GENERATED_DIR 	=	$(SPHINX_BUILD_DIR)/../generated
 
-.PHONY: help install copy-images apidoc remove-generated html Makefile
+.PHONY: help install copy-images apidoc remove-generated html generate Makefile
 
 # Copy images before running any Sphinx command (except for help)
 copy-images:
@@ -27,17 +27,26 @@ generate-yaml-index:
 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
+	@echo "Generating Ansible roles index..."
+	python generators/index.py --roles-dir generated/roles --output-file $(SPHINX_SOURCE_DIR)/roles/ansible_role_glosar.rst --caption "Ansible Role Glosar"
+	
+generate-readmes:	
+	@echo "Create required README.md's for index..."
+	python generators/readmes.py --generated-dir ./$(SPHINX_GENERATED_DIR)
+
+generate: generate-apidoc generate-yaml-index generate-ansible-roles generate-readmes
+
 
 remove-generated:
 	@echo "Removing generated files..."
 	- find $(SPHINX_GENERATED_DIR)/ -type f ! -name '.gitkeep' -delete
 
-# "help" target does not copy images
 help:
 	@$(SPHINXBUILD) -M help "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS) $(O)
 
-html: copy-images generate-apidoc generate-ansible-roles generate-yaml-index
-	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)
+html: copy-images generate
+	@echo "Building Sphinx documentation..."
+	$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)
 
 just-html:
 	@$(SPHINXBUILD) -M html "$(SPHINX_SOURCE_DIR)" "$(SPHINX_BUILD_DIR)" $(SPHINXOPTS)

docs/generators/ansible_roles.py

@@ -1,6 +1,21 @@
 import os
 import yaml
 import argparse
+import subprocess
+
+def convert_md_to_rst(md_content):
+    """Convert Markdown content to reStructuredText using Pandoc."""
+    try:
+        result = subprocess.run(
+            ["pandoc", "-f", "markdown", "-t", "rst"],
+            input=md_content.encode("utf-8"),
+            capture_output=True,
+            check=True
+        )
+        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
 
 def generate_ansible_roles_doc(roles_dir, output_dir):
     """Generates reStructuredText documentation for Ansible roles."""
@@ -18,18 +33,27 @@ def generate_ansible_roles_doc(roles_dir, output_dir):
 
             role_doc = os.path.join(output_dir, f"{role}.rst")
             with open(role_doc, "w", encoding="utf-8") as f:
+                # Hauptüberschrift
                 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")
+                # Unterüberschrift für Variablen
+                f.write("Variables\n")
+                f.write("---------\n\n")
+
                 for key, value in meta_data.get('galaxy_info', {}).items():
                     f.write(f"- **{key}**: {value}\n")
 
+                # README falls vorhanden konvertieren und einfügen
                 if os.path.exists(readme_file):
-                    f.write("\n### README\n")
+                    f.write("\nREADME\n")
+                    f.write("------\n\n")
                     with open(readme_file, "r", encoding="utf-8") as readme:
-                        f.write("\n" + readme.read())
+                        markdown_content = readme.read()
+                        rst_content = convert_md_to_rst(markdown_content)
+                        f.write(rst_content)
 
     print(f"Ansible roles documentation has been generated in {output_dir}")
 
@@ -40,3 +64,4 @@ if __name__ == "__main__":
 
     args = parser.parse_args()
     generate_ansible_roles_doc(args.roles_dir, args.output_dir)
+

docs/generators/index.py

@@ -0,0 +1,40 @@
+import os
+import argparse
+
+def generate_ansible_roles_index(roles_dir, output_file, caption: str):
+    """Generates an index.rst file listing all .rst files in the given directory."""
+    
+    roles_dir = os.path.abspath(roles_dir)
+    output_file = os.path.abspath(output_file)
+    output_dir = os.path.dirname(output_file)
+
+    if not os.path.exists(roles_dir):
+        print(f"Error: Directory {roles_dir} does not exist.")
+        return
+    
+    os.makedirs(output_dir, exist_ok=True)
+
+    rst_files = [f for f in os.listdir(roles_dir) if f.endswith(".rst")]
+    rst_files.sort()  # Alphabetisch sortieren
+
+    # Berechne relative Pfade zur korrekten Verlinkung
+    rel_paths = [os.path.relpath(os.path.join(roles_dir, f), start=output_dir) for f in rst_files]
+
+    with open(output_file, "w", encoding="utf-8") as f:
+        f.write(f"{caption}\n===================\n\n")
+        f.write(f".. toctree::\n   :maxdepth: 1\n   :caption: {caption}\n\n")
+        
+        for rel_path in rel_paths:
+            file_name_without_ext = os.path.splitext(rel_path)[0]
+            f.write(f"   {file_name_without_ext}\n")
+
+    print(f"Index generated at {output_file}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Generate an index for documentation.")
+    parser.add_argument("--roles-dir", required=True, help="Directory containing .rst files.")
+    parser.add_argument("--output-file", required=True, help="Path to the output index.rst file.")
+    parser.add_argument("--caption", required=True, help="The index title")
+
+    args = parser.parse_args()
+    generate_ansible_roles_index(args.roles_dir, args.output_file, args.caption)

docs/generators/readmes.py

@@ -0,0 +1,37 @@
+import os
+import argparse
+
+def create_readme_in_subdirs(generated_dir):
+    """
+    Creates a README.md file in each subdirectory of generated_dir.
+    The README will contain a title based on the subdirectory name.
+    """
+    generated_dir = os.path.abspath(generated_dir)
+
+    if not os.path.exists(generated_dir):
+        print(f"Error: Directory {generated_dir} does not exist.")
+        return
+
+    for root, dirs, _ in os.walk(generated_dir):
+        for subdir in dirs:
+            subdir_path = os.path.join(root, subdir)
+            readme_path = os.path.join(subdir_path, "README.md")
+
+            folder_base_name = os.path.basename(subdir)
+
+            readme_content = f"""\
+# Auto Generated Technical Documentation: {folder_base_name}
+
+This folder contains an auto-generated technical role documentation for CyMaIS.
+"""
+
+            with open(readme_path, "w", encoding="utf-8") as f:
+                f.write(readme_content)
+            print(f"README.md created at {readme_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Create README.md files in all subdirectories of the given directory.")
+    parser.add_argument("--generated-dir", required=True, help="Path to the generated directory.")
+
+    args = parser.parse_args()
+    create_readme_in_subdirs(args.generated_dir)

docs/requirements.txt

@@ -5,3 +5,4 @@ docutils
 sphinx-jinja
 sphinxcontrib-yaml
 pathspec
+markdown2