|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# -*- coding: utf-8; py-indent-offset: 4 -*- |
| 3 | +# |
| 4 | +# Author: Linuxfabrik GmbH, Zurich, Switzerland |
| 5 | +# Contact: info (at) linuxfabrik (dot) ch |
| 6 | +# https://www.linuxfabrik.ch/ |
| 7 | +# License: The Unlicense, see LICENSE file. |
| 8 | + |
| 9 | +"""Generates the docs/ directory structure with symlinks and the mkdocs.yml navigation |
| 10 | +for the Linuxfabrik Monitoring Plugins documentation site. |
| 11 | +
|
| 12 | +Run this tool from the repository root directory. |
| 13 | +""" |
| 14 | + |
| 15 | +import os |
| 16 | +import sys |
| 17 | + |
| 18 | +__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland' |
| 19 | +__version__ = '2026040701' |
| 20 | + |
| 21 | +REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) |
| 22 | +DOCS_DIR = os.path.join(REPO_ROOT, 'docs') |
| 23 | + |
| 24 | +# Top-level markdown files to include in the documentation. |
| 25 | +# Format: (source filename, target filename in docs/, nav title) |
| 26 | +TOP_LEVEL_DOCS = [ |
| 27 | + ('BUILD.md', 'build.md', 'Compiling and Packaging'), |
| 28 | + ('CHANGELOG.md', 'CHANGELOG.md', None), |
| 29 | + ('CODE_OF_CONDUCT.md', 'CODE_OF_CONDUCT.md', None), |
| 30 | + ('CONTRIBUTING.md', 'contributing.md', 'Contributing'), |
| 31 | + ('GRAFANA.md', 'grafana.md', 'Grafana'), |
| 32 | + ('ICINGA.md', 'icinga.md', 'Icinga Setup'), |
| 33 | + ('INSTALL.md', 'install.md', 'Installation'), |
| 34 | + ('PLUGINS-KEYCLOAK.md', 'plugins-keycloak.md', 'Plugin Group: Keycloak'), |
| 35 | + ('PLUGINS-MYSQL.md', 'plugins-mysql.md', 'Plugin Group: MySQL'), |
| 36 | + ('PLUGINS-ROCKETCHAT.md', 'plugins-rocketchat.md', 'Plugin Group: Rocket.Chat'), |
| 37 | + ('PLUGINS-WILDFLY.md', 'plugins-wildfly.md', 'Plugin Group: WildFly'), |
| 38 | + ('SECURITY.md', 'security.md', 'Security'), |
| 39 | +] |
| 40 | + |
| 41 | +# Plugin directories to scan |
| 42 | +PLUGIN_DIRS = [ |
| 43 | + ('check-plugins', 'Check Plugins'), |
| 44 | + ('notification-plugins', 'Notification Plugins'), |
| 45 | + ('event-plugins', 'Event Plugins'), |
| 46 | +] |
| 47 | + |
| 48 | + |
| 49 | +def create_symlink(source, target): |
| 50 | + """Create a relative symlink from target to source.""" |
| 51 | + target_dir = os.path.dirname(target) |
| 52 | + rel_source = os.path.relpath(source, target_dir) |
| 53 | + if os.path.islink(target): |
| 54 | + os.unlink(target) |
| 55 | + elif os.path.exists(target): |
| 56 | + os.unlink(target) |
| 57 | + os.symlink(rel_source, target) |
| 58 | + |
| 59 | + |
| 60 | +def scan_plugins(plugin_dir): |
| 61 | + """Scan a plugin directory and return sorted list of plugin names that have a README.md.""" |
| 62 | + full_path = os.path.join(REPO_ROOT, plugin_dir) |
| 63 | + if not os.path.isdir(full_path): |
| 64 | + return [] |
| 65 | + plugins = [] |
| 66 | + for entry in sorted(os.listdir(full_path)): |
| 67 | + if entry == 'example': |
| 68 | + continue |
| 69 | + readme = os.path.join(full_path, entry, 'README.md') |
| 70 | + if os.path.isfile(readme): |
| 71 | + plugins.append(entry) |
| 72 | + return plugins |
| 73 | + |
| 74 | + |
| 75 | +def generate_mkdocs_yml(nav_sections): |
| 76 | + """Generate the mkdocs.yml content.""" |
| 77 | + lines = [] |
| 78 | + lines.append("# This file is auto-generated by tools/build-docs. Do not edit manually.") |
| 79 | + lines.append("") |
| 80 | + lines.append("site_name: 'Linuxfabrik Monitoring Plugins'") |
| 81 | + lines.append("site_url: 'https://linuxfabrik.github.io/monitoring-plugins/'") |
| 82 | + lines.append("repo_url: 'https://github.com/Linuxfabrik/monitoring-plugins'") |
| 83 | + lines.append("repo_name: 'Linuxfabrik/monitoring-plugins'") |
| 84 | + lines.append("") |
| 85 | + lines.append("theme:") |
| 86 | + lines.append(" name: 'material'") |
| 87 | + lines.append(" icon:") |
| 88 | + lines.append(" logo: 'material/monitor-dashboard'") |
| 89 | + lines.append(" palette:") |
| 90 | + lines.append(" - scheme: 'default'") |
| 91 | + lines.append(" primary: 'blue grey'") |
| 92 | + lines.append(" accent: 'orange'") |
| 93 | + lines.append(" toggle:") |
| 94 | + lines.append(" icon: 'material/brightness-7'") |
| 95 | + lines.append(" name: 'Switch to dark mode'") |
| 96 | + lines.append(" - scheme: 'slate'") |
| 97 | + lines.append(" primary: 'blue grey'") |
| 98 | + lines.append(" accent: 'orange'") |
| 99 | + lines.append(" toggle:") |
| 100 | + lines.append(" icon: 'material/brightness-4'") |
| 101 | + lines.append(" name: 'Switch to light mode'") |
| 102 | + lines.append(" features:") |
| 103 | + lines.append(" - content.code.copy") |
| 104 | + lines.append(" - navigation.expand") |
| 105 | + lines.append(" - navigation.instant") |
| 106 | + lines.append(" - navigation.sections") |
| 107 | + lines.append(" - navigation.top") |
| 108 | + lines.append(" - search.highlight") |
| 109 | + lines.append(" - search.suggest") |
| 110 | + lines.append(" - toc.follow") |
| 111 | + lines.append("") |
| 112 | + lines.append("markdown_extensions:") |
| 113 | + lines.append(" - admonition") |
| 114 | + lines.append(" - attr_list") |
| 115 | + lines.append(" - def_list") |
| 116 | + lines.append(" - tables") |
| 117 | + lines.append(" - toc:") |
| 118 | + lines.append(" permalink: true") |
| 119 | + lines.append("") |
| 120 | + lines.append("plugins:") |
| 121 | + lines.append(" - search") |
| 122 | + lines.append("") |
| 123 | + lines.append("not_in_nav: |") |
| 124 | + lines.append(" CHANGELOG.md") |
| 125 | + lines.append(" CODE_OF_CONDUCT.md") |
| 126 | + lines.append("") |
| 127 | + |
| 128 | + # Build nav |
| 129 | + lines.append("nav:") |
| 130 | + lines.append(" - 'Home': 'index.md'") |
| 131 | + lines.append(" - 'Installation': 'install.md'") |
| 132 | + lines.append(" - 'Icinga Setup': 'icinga.md'") |
| 133 | + lines.append(" - 'Grafana': 'grafana.md'") |
| 134 | + |
| 135 | + for section_dir, section_title, plugins in nav_sections: |
| 136 | + lines.append(f" - '{section_title}':") |
| 137 | + for plugin in plugins: |
| 138 | + lines.append(f" - '{plugin}': '{section_dir}/{plugin}.md'") |
| 139 | + |
| 140 | + lines.append(" - 'Plugin Groups':") |
| 141 | + lines.append(" - 'Keycloak': 'plugins-keycloak.md'") |
| 142 | + lines.append(" - 'MySQL': 'plugins-mysql.md'") |
| 143 | + lines.append(" - 'Rocket.Chat': 'plugins-rocketchat.md'") |
| 144 | + lines.append(" - 'WildFly': 'plugins-wildfly.md'") |
| 145 | + lines.append(" - 'Compiling and Packaging': 'build.md'") |
| 146 | + lines.append(" - 'Contributing': 'contributing.md'") |
| 147 | + lines.append(" - 'Security': 'security.md'") |
| 148 | + lines.append("") |
| 149 | + |
| 150 | + return '\n'.join(lines) |
| 151 | + |
| 152 | + |
| 153 | +def main(): |
| 154 | + os.makedirs(DOCS_DIR, exist_ok=True) |
| 155 | + |
| 156 | + # Create symlinks for top-level docs |
| 157 | + for source_name, target_name, _ in TOP_LEVEL_DOCS: |
| 158 | + source = os.path.join(REPO_ROOT, source_name) |
| 159 | + target = os.path.join(DOCS_DIR, target_name) |
| 160 | + if os.path.isfile(source): |
| 161 | + create_symlink(source, target) |
| 162 | + else: |
| 163 | + print(f'WARNING: {source_name} not found, skipping.') |
| 164 | + |
| 165 | + # Create symlinks for plugin READMEs |
| 166 | + nav_sections = [] |
| 167 | + for plugin_dir, section_title in PLUGIN_DIRS: |
| 168 | + plugins = scan_plugins(plugin_dir) |
| 169 | + if not plugins: |
| 170 | + continue |
| 171 | + |
| 172 | + target_dir = os.path.join(DOCS_DIR, plugin_dir) |
| 173 | + os.makedirs(target_dir, exist_ok=True) |
| 174 | + |
| 175 | + # Remove stale symlinks |
| 176 | + expected_files = {f'{plugin}.md' for plugin in plugins} |
| 177 | + for entry in os.listdir(target_dir): |
| 178 | + entry_path = os.path.join(target_dir, entry) |
| 179 | + if os.path.islink(entry_path) and entry not in expected_files: |
| 180 | + os.unlink(entry_path) |
| 181 | + |
| 182 | + for plugin in plugins: |
| 183 | + source = os.path.join(REPO_ROOT, plugin_dir, plugin, 'README.md') |
| 184 | + target = os.path.join(target_dir, f'{plugin}.md') |
| 185 | + create_symlink(source, target) |
| 186 | + |
| 187 | + nav_sections.append((plugin_dir, section_title, plugins)) |
| 188 | + |
| 189 | + # Generate mkdocs.yml |
| 190 | + mkdocs_content = generate_mkdocs_yml(nav_sections) |
| 191 | + mkdocs_path = os.path.join(REPO_ROOT, 'mkdocs.yml') |
| 192 | + with open(mkdocs_path, 'w') as f: |
| 193 | + f.write(mkdocs_content) |
| 194 | + |
| 195 | + # Count |
| 196 | + total_symlinks = len(TOP_LEVEL_DOCS) |
| 197 | + for _, _, plugins in nav_sections: |
| 198 | + total_symlinks += len(plugins) |
| 199 | + print(f'Created {total_symlinks} symlinks in docs/') |
| 200 | + print(f'Generated mkdocs.yml with {sum(len(p) for _, _, p in nav_sections)} plugin entries') |
| 201 | + |
| 202 | + return 0 |
| 203 | + |
| 204 | + |
| 205 | +if __name__ == '__main__': |
| 206 | + sys.exit(main()) |
0 commit comments