From 9194abee4a3b2cdb039564dea7b5dc5af809362c Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Mon, 17 Mar 2025 03:41:54 +0100 Subject: [PATCH] Doc optimations --- 02_VISION.md | 6 --- README.md | 4 +- group_vars/README.md | 1 + index.rst | 3 ++ sphinx/conf.py | 4 +- sphinx/extensions/markdown_include.py | 43 +++++++++++++++---- .../{_templates => templates}/structure.html | 6 +-- 7 files changed, 46 insertions(+), 21 deletions(-) create mode 100644 group_vars/README.md rename sphinx/{_templates => templates}/structure.html (100%) diff --git a/02_VISION.md b/02_VISION.md index 199a45de..79b23c65 100644 --- a/02_VISION.md +++ b/02_VISION.md @@ -9,9 +9,3 @@ We envision a future where businesses are no longer constrained by the complexit Our commitment is to break down barriers to advanced IT infrastructure, democratizing access to high-level technology solutions. By harnessing the power of Open Source, our solution will not only uphold the highest standards of security and scalability but also foster a community-driven approach to continuous improvement and innovation. In essence, our vision is to redefine the paradigm of IT infrastructure deployment, making it a swift, secure, and scalable journey for every business, and setting a new benchmark in the industry for efficiency and reliability. - ---- - -Kevin Veen-Birkenbach -Berlin -2023-12-13 diff --git a/README.md b/README.md index f41900af..2ba1a3c8 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # CyMaIS - Cyber Master Infrastructure Solution - - Welcome to CyMaIS (Cyber Master Infrastructure Solution), a transformative tool designed to redefine IT infrastructure setup for organizations and individuals alike. At its core, CyMaIS leverages the power of Docker, Linux, and Ansible to offer a streamlined, automated solution for deploying and managing IT systems. + + Whether you're a small startup, a growing enterprise, or an individual seeking efficient IT management, CyMaIS provides a comprehensive suite of tools that cater to a wide range of needs. From simple system setups to complex server configurations and end-user PC management, CyMaIS simplifies the entire process. Our intuitive interface, coupled with in-depth documentation, makes it accessible to both tech-savvy users and those with limited IT experience. diff --git a/group_vars/README.md b/group_vars/README.md new file mode 100644 index 00000000..af4abbfe --- /dev/null +++ b/group_vars/README.md @@ -0,0 +1 @@ +# Configuration \ No newline at end of file diff --git a/index.rst b/index.rst index fd942e6d..616c03b8 100644 --- a/index.rst +++ b/index.rst @@ -1 +1,4 @@ +About +=============================== + .. markdown-include:: README.md \ No newline at end of file diff --git a/sphinx/conf.py b/sphinx/conf.py index dbb4a909..5f9b0fbc 100644 --- a/sphinx/conf.py +++ b/sphinx/conf.py @@ -17,7 +17,7 @@ author = 'Kevin Veen-Birkenbach' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -templates_path = ['_templates'] +templates_path = ['templates'] exclude_patterns = ['docs', 'venv', 'venv/**'] @@ -26,7 +26,7 @@ exclude_patterns = ['docs', 'venv', 'venv/**'] # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = 'sphinxawesome_theme' -html_static_path = ['_static'] +html_static_path = ['static'] html_sidebars = { '**': [ diff --git a/sphinx/extensions/markdown_include.py b/sphinx/extensions/markdown_include.py index cbd730f4..360e5aa1 100644 --- a/sphinx/extensions/markdown_include.py +++ b/sphinx/extensions/markdown_include.py @@ -8,24 +8,24 @@ logger = logging.getLogger(__name__) from myst_parser.parsers.sphinx_ import MystParser class MarkdownIncludeDirective(Directive): - required_arguments = 1 # Pfad zur Markdown-Datei + required_arguments = 1 # Path to the Markdown file optional_arguments = 0 final_argument_whitespace = True has_content = False def run(self): - logger.info("markdown-include-Direktive wird ausgeführt") + logger.info("Executing markdown-include directive") env = self.state.document.settings.env - # Ermittle den absoluten Pfad der Datei. + # Determine the absolute path of the file. rel_filename, filename = env.relfn2path(self.arguments[0]) - logger.info("Markdown-Datei: %s", filename) + logger.info("Markdown file: %s", filename) if not os.path.exists(filename): error = self.state_machine.reporter.error( f'File not found: {filename}', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] - + try: with open(filename, 'r', encoding='utf-8') as f: markdown_content = f.read() @@ -36,16 +36,43 @@ class MarkdownIncludeDirective(Directive): line=self.lineno) return [error] - # Parse den Markdown-Content mit MystParser. + # Parse the Markdown content with MystParser. parser = MystParser() from docutils.frontend import OptionParser from docutils.utils import new_document settings = OptionParser(components=(MystParser,)).get_default_values() - # Hänge die Sphinx-Umgebung an die Einstellungen an, damit myst_parser funktioniert. + # Attach the Sphinx environment to the settings so that myst_parser works. settings.env = self.state.document.settings.env doc = new_document(filename, settings=settings) parser.parse(markdown_content, doc) - logger.info("Markdown-Parsing erfolgreich abgeschlossen") + logger.info("Markdown parsing completed successfully") + + # Remove the first header (title) if it exists. + if doc.children: + first_section = doc.children[0] + if isinstance(first_section, nodes.section) and first_section.children: + first_child = first_section.children[0] + if isinstance(first_child, nodes.title): + # If there are additional children, remove the title node. + if len(first_section.children) > 1: + first_section.pop(0) + logger.info("Removed first header from Markdown content") + else: + # If it's the only child, clear its content instead. + first_child.clear() + logger.info("Cleared text of first header from Markdown content") + + # Unwrap the first section if it no longer has a title. + if isinstance(first_section, nodes.section): + has_title = any(isinstance(child, nodes.title) and child.astext().strip() + for child in first_section.children) + if not has_title: + # Remove the section wrapper so that its content does not create a TOC entry. + unwrapped = list(first_section.children) + # Replace the first section with its children. + doc.children = unwrapped + doc.children[1:] + logger.info("Unwrapped first section to avoid a TOC entry") + return doc.children def setup(app): diff --git a/sphinx/_templates/structure.html b/sphinx/templates/structure.html similarity index 100% rename from sphinx/_templates/structure.html rename to sphinx/templates/structure.html index b3d446c6..9027c665 100644 --- a/sphinx/_templates/structure.html +++ b/sphinx/templates/structure.html @@ -34,11 +34,11 @@ {% if local_md_headings or local_subfolders %}

Index

- {% if local_subfolders %} - {{ render_headings(local_subfolders) }} - {% endif %} {% if local_md_headings %} {{ render_headings(local_md_headings) }} {% endif %} + {% if local_subfolders %} + {{ render_headings(local_subfolders) }} + {% endif %}
{% endif %}