Finished optimization for today

05_CUSTOMER_GUIDE.md

@@ -1,4 +1,4 @@
-# Enterprise Solutions
+# Customer Guide
 <img src="https://cybermaster.space/wp-content/uploads/sites/7/2023/11/FVG_8364BW-scaled.jpg" width="300" style="float: right; margin-left: 30px;">
 
 My name is Kevin Veen-Birkenbach and I'm glad to assist you in the implementation of your secure and scalable IT infrastrucutre solution with CyMaIS.

07_SETUP_GUIDE.md

@@ -1,4 +1,4 @@
-# Setup
+# Setup Guide
 
 To setup CyMaIS follow this steps: 
 

11_DONATE.md

@@ -1,6 +1,6 @@
 # Support Us
 
-CyMaIS is a transformative tool designed to redefine IT infrastructure setup for organizations and individuals alike. Your contributions directly support the ongoing development and innovation behind CyMaIS, ensuring that it continues to grow and serve its community effectively.
+CyMaIS is an Open Source Based transformative tool designed to redefine IT infrastructure setup for organizations and individuals alike. Your contributions directly support the ongoing development and innovation behind CyMaIS, ensuring that it continues to grow and serve its community effectively.
 
 If you enjoy using CyMaIS and would like to contribute to its improvement, please consider donating. Every contribution, no matter the size, helps us maintain and expand this project.
 

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

roles/.gitignore

@@ -0,0 +1 @@
+ansible_role_glosar.rst

roles/README.md

@@ -0,0 +1,13 @@
+# Applications and Roles
+CyMaIS offers a variety of applications to simplify your daily tasks.  
+
+## For Users  
+Discover the solutions CyMaIS provides for you:  
+- [Application Glossary](application_glosar.rst)  
+- [Application Categories](application_categories.rst)  
+
+## For Developers
+Explore the technical details of our roles:  
+- [Ansible Role Glossary](ansible_role_glosar.rst)  
+
+Want to dive deeper into the source code or our ansible roles? Check out our [GitHub repository](https://github.com/kevinveenbirkenbach/cymais/tree/master/roles).  

roles/index.rst

@@ -1,5 +0,0 @@
-Applications
-=====================================
-
-- :doc:`Glosar <glosar>`
-- :doc:`Categories <categories>`