From 12e0367c66bd67f9c7d3f5746034590ca5524025 Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Sat, 15 Mar 2025 16:10:02 +0100
Subject: [PATCH] Optimized sphinx

---
 docs/.gitkeep                         |  0
 index.rst                             |  5 +---
 roles/README.md                       |  5 ++--
 roles/categories.rst                  |  3 +++
 roles/glosar.rst                      |  8 ++++++
 roles/index.rst                       |  6 ++---
 sphinx/_templates/local_md_files.html |  2 +-
 sphinx/local_md_files.py              |  7 ++---
 sphinx/roles_overview.py              | 39 ++++++++++++++++++---------
 9 files changed, 47 insertions(+), 28 deletions(-)
 delete mode 100644 docs/.gitkeep
 create mode 100644 roles/categories.rst
 create mode 100644 roles/glosar.rst

diff --git a/docs/.gitkeep b/docs/.gitkeep
deleted file mode 100644
index e69de29b..00000000
diff --git a/index.rst b/index.rst
index ff3a35d4..50658d53 100644
--- a/index.rst
+++ b/index.rst
@@ -7,7 +7,4 @@ Cyber Master Infrastructure Solution documentation
    :glob:
 
    *
-   roles/index.rst
-
-
-.. roles-overview::
\ No newline at end of file
+   roles/index.rst
\ No newline at end of file
diff --git a/roles/README.md b/roles/README.md
index 6df18ae0..aadd1bde 100644
--- a/roles/README.md
+++ b/roles/README.md
@@ -1,3 +1,2 @@
-test
-
-# h1
\ No newline at end of file
+#  Hello World
+test
\ No newline at end of file
diff --git a/roles/categories.rst b/roles/categories.rst
new file mode 100644
index 00000000..d5c17e3a
--- /dev/null
+++ b/roles/categories.rst
@@ -0,0 +1,3 @@
+# Applications by Category
+
+.. roles-overview::
\ No newline at end of file
diff --git a/roles/glosar.rst b/roles/glosar.rst
new file mode 100644
index 00000000..9a0e26d0
--- /dev/null
+++ b/roles/glosar.rst
@@ -0,0 +1,8 @@
+# Application Glosar
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Included Applications:
+   :glob:
+
+   */README
\ No newline at end of file
diff --git a/roles/index.rst b/roles/index.rst
index fbe78e4f..7d33d4d5 100644
--- a/roles/index.rst
+++ b/roles/index.rst
@@ -6,8 +6,6 @@ Applications and Roles
 
 .. toctree::
    :maxdepth: 1
-   :caption: Included Applications:
+   :caption: Overview
    :glob:
-
-   */README
-
+   ./*.rst
diff --git a/sphinx/_templates/local_md_files.html b/sphinx/_templates/local_md_files.html
index c58e1984..83743b9c 100644
--- a/sphinx/_templates/local_md_files.html
+++ b/sphinx/_templates/local_md_files.html
@@ -14,7 +14,7 @@
         </ul>
       {% endfor %}
     {% endif %}
-    <li><a href="{{ pathto(item.link) }}">{{ item.text }}</a></li>
+    <li><a href="{{ pathto(item.link).replace("#","") + "#" + item.anchor}}">{{ item.text }}</a></li>
     {% set ns.current_level = item.level %}
   {% endfor %}
   {# Close any remaining open <ul> tags #}
diff --git a/sphinx/local_md_files.py b/sphinx/local_md_files.py
index 28fd71a8..0ef4bb1b 100644
--- a/sphinx/local_md_files.py
+++ b/sphinx/local_md_files.py
@@ -68,12 +68,13 @@ def add_local_md_headings(app, pagename, templatename, context, doctree):
             filepath = os.path.join(abs_dir, file)
             headings = extract_headings_from_file(filepath)
             for heading in headings:
-                file_link = os.path.join(directory, file) if directory else file
-                full_link = file_link + '#' + heading['anchor']
+                # Build file link: zunächst Pfad + Dateiname, dann Ersetzen der .md-Endung durch .html
+                file_link = os.path.join(directory, file).replace(".md","") if directory else file
                 local_md_headings.append({
                     'level': heading['level'],
                     'text': heading['text'],
-                    'link': full_link
+                    'link': file_link,
+                    'anchor': heading['anchor']
                 })
     # Sort headings in natural ascending order using natural_sort_key.
     local_md_headings.sort(key=lambda x: natural_sort_key(x['text']))
diff --git a/sphinx/roles_overview.py b/sphinx/roles_overview.py
index 78cf60b9..6ce33de3 100644
--- a/sphinx/roles_overview.py
+++ b/sphinx/roles_overview.py
@@ -13,8 +13,9 @@ class RolesOverviewDirective(Directive):
     A directive to embed a roles overview as reStructuredText.
     
     It scans the roles directory (i.e. every folder under "roles") for a
-    "meta/main.yml" file, reads the category (if provided) and the role’s description
-    (from galaxy_info.description), and outputs a listing grouped by category.
+    "meta/main.yml" file, reads the role’s galaxy tags (from galaxy_info.galaxy_tags)
+    and description (from galaxy_info.description), and outputs a listing grouped
+    by each tag. Roles without galaxy tags are grouped under "uncategorized".
     """
     has_content = False
 
@@ -28,7 +29,7 @@ class RolesOverviewDirective(Directive):
                 "Roles directory not found.", line=self.lineno)
             return [error_node]
 
-        # Dictionary mapping categories to role entries.
+        # Dictionary mapping tags to role entries.
         categories = {}
         for role_path in glob.glob(os.path.join(roles_dir, '*')):
             if os.path.isdir(role_path):
@@ -42,38 +43,50 @@ class RolesOverviewDirective(Directive):
                         continue
 
                     role_name = os.path.basename(role_path)
-                    category = data.get('category', 'uncategorized')
-                    role_description = data.get('galaxy_info', {}).get('description', '')
+                    # Try to get galaxy_tags from galaxy_info. If none, use "uncategorized".
+                    galaxy_info = data.get('galaxy_info', {})
+                    tags = galaxy_info.get('galaxy_tags', [])
+                    if not tags:
+                        tags = ['uncategorized']
+                    role_description = galaxy_info.get('description', '')
                     role_entry = {
                         'name': role_name,
                         'description': role_description,
-                        'link': f'roles/{role_name}/README.md'
+                        'link': f'roles/{role_name}/README.md',
+                        'tags': tags,
                     }
-                    categories.setdefault(category, []).append(role_entry)
+                    # Add this role to every tag it belongs to.
+                    for tag in tags:
+                        categories.setdefault(tag, []).append(role_entry)
                 else:
                     logger.warning(f"meta/main.yml not found for role {role_path}")
+                logger.info("For role %s, galaxy_info: %s", role_name, galaxy_info)
 
         # Sort categories and roles alphabetically.
         sorted_categories = sorted(categories.items(), key=lambda x: x[0].lower())
-        for category, roles in sorted_categories:
+        for tag, roles in sorted_categories:
             roles.sort(key=lambda r: r['name'].lower())
 
         # Build reStructuredText content.
         lines = []
-        for category, roles in sorted_categories:
-            lines.append(f".. rubric:: {category}")
+        for tag, roles in sorted_categories:
+            lines.append(f".. rubric:: {tag}")
             lines.append("")
             for role in roles:
-                lines.append(f"* **[`{role['name']}`]({role['link']})**")
+                # Render the role name as a hyperlink in reStructuredText.
+                lines.append(f"* `{role['name']} <{role['link']}>`_")
+                # Insert a line break before the description.
                 if role['description']:
-                    lines.append(f"  - {role['description']}")
+                    lines.append("")
+                    lines.append(f"  {role['description']}")
+                lines.append("")
             lines.append("")
 
         rst_content = "\n".join(lines)
 
         # Use a ViewList for nested_parse.
         rst_lines = ViewList()
-        for i, line in enumerate(rst_content.splitlines()):
+        for line in rst_content.splitlines():
             rst_lines.append(line, '<roles-overview>')
 
         container = nodes.container()