diff --git a/03_SECURITY.md b/03_SECURITY_GUIDELINES.md similarity index 100% rename from 03_SECURITY.md rename to 03_SECURITY_GUIDELINES.md diff --git a/09_ENTERPRISE_SOLUTIONS.md b/05_CUSTOMER_GUIDE.md similarity index 97% rename from 09_ENTERPRISE_SOLUTIONS.md rename to 05_CUSTOMER_GUIDE.md index c70a301b..cbc98ac0 100644 --- a/09_ENTERPRISE_SOLUTIONS.md +++ b/05_CUSTOMER_GUIDE.md @@ -1,4 +1,4 @@ -# Enterprise Solutions +# Customer Guide 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. diff --git a/06_ADMINISTRATOR_GUIDE.md b/06_ADMINISTRATOR_GUIDE.md new file mode 100644 index 00000000..e69de29b diff --git a/06_CONFIGURATION.md b/07_CONFIGURATION.md similarity index 100% rename from 06_CONFIGURATION.md rename to 07_CONFIGURATION.md diff --git a/05_SETUP.md b/07_SETUP_GUIDE.md similarity index 97% rename from 05_SETUP.md rename to 07_SETUP_GUIDE.md index 09b33a9f..5d7542d5 100644 --- a/05_SETUP.md +++ b/07_SETUP_GUIDE.md @@ -1,4 +1,4 @@ -# Setup +# Setup Guide To setup CyMaIS follow this steps: diff --git a/07_DEPLOY.md b/08_DEPLOY.md similarity index 100% rename from 07_DEPLOY.md rename to 08_DEPLOY.md diff --git a/08_DEVELOPER_GUIDE.rst b/09_DEVELOPER_GUIDE.rst similarity index 100% rename from 08_DEVELOPER_GUIDE.rst rename to 09_DEVELOPER_GUIDE.rst diff --git a/11_DONATE.md b/11_DONATE.md index 54146ebd..9044522a 100644 --- a/11_DONATE.md +++ b/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. diff --git a/docs/Makefile b/docs/Makefile index 5b073fe9..ae41b7bc 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/generators/ansible_roles.py b/docs/generators/ansible_roles.py index e7b50bf0..78027d5b 100644 --- a/docs/generators/ansible_roles.py +++ b/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) + diff --git a/docs/generators/index.py b/docs/generators/index.py new file mode 100644 index 00000000..a75f1b35 --- /dev/null +++ b/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) diff --git a/docs/generators/readmes.py b/docs/generators/readmes.py new file mode 100644 index 00000000..6a963762 --- /dev/null +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt index 29a4c88d..1a22372b 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ docutils sphinx-jinja sphinxcontrib-yaml pathspec +markdown2 \ No newline at end of file diff --git a/roles/.gitignore b/roles/.gitignore new file mode 100644 index 00000000..b43db1de --- /dev/null +++ b/roles/.gitignore @@ -0,0 +1 @@ +ansible_role_glosar.rst \ No newline at end of file diff --git a/roles/README.md b/roles/README.md new file mode 100644 index 00000000..b5d35c7d --- /dev/null +++ b/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). \ No newline at end of file diff --git a/roles/categories.rst b/roles/application_categories.rst similarity index 100% rename from roles/categories.rst rename to roles/application_categories.rst diff --git a/roles/glosar.rst b/roles/application_glosar.rst similarity index 100% rename from roles/glosar.rst rename to roles/application_glosar.rst diff --git a/roles/index.rst b/roles/index.rst deleted file mode 100644 index 6e2be6d3..00000000 --- a/roles/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -Applications -===================================== - -- :doc:`Glosar ` -- :doc:`Categories `