♻️ (docs): Replace prepare-docs script with MkDocs plugins

.github/workflows/release.yaml

@@ -49,9 +49,6 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Prepare docs
-        run: ./docs/hack/prepare-docs.sh "${{ github.server_url }}/${{ github.repository }}"
-
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -74,9 +71,6 @@ jobs:
         working-directory: docs
         run: mkdocs build
 
-      - name: Remove sitemap.xml.gz
-        run: rm docs/site/sitemap.xml.gz
-
       - name: Deploy docs
         uses: JamesIves/github-pages-deploy-action@v4
         with:

docs/mkdocs.yml

@@ -41,6 +41,11 @@ plugins:
       cache_safe: true
       css_files:
         - stylesheets/extra.css
+  - mkdocs-simple-hooks:
+      hooks:
+        on_files: plugins.add_files:main
+        on_page_markdown: plugins.filter_readmes:main
+        on_post_build: plugins.remove_sitemap_gz:main
 
 markdown_extensions:
   - attr_list

docs/plugins/add_files.py

@@ -0,0 +1,41 @@
+import os
+
+from mkdocs.config.base import Config
+from mkdocs.structure.files import File, Files
+
+
+def main(files: Files, config: Config):
+    files.append(readme_file(config))
+
+    charts = []
+    for root, dirs, dirFiles in os.walk("../charts"):
+        for file in dirFiles:
+            if file.endswith(".md"):
+                charts.append(os.path.join(root, file))
+    charts.sort()
+    for path in charts:
+        files.append(chart_file(path, config))
+
+    return files
+
+
+def readme_file(config: Config):
+    return File(
+        path="README.md",
+        src_dir="..",
+        dest_dir=config.site_dir,
+        use_directory_urls=config.use_directory_urls
+    )
+
+
+def chart_file(src_path: str, config: Config):
+    src_dir = os.path.dirname(src_path)
+    chart_name = os.path.basename(src_dir)
+    f = File(
+        path=os.path.join("charts", chart_name + ".md"),
+        src_dir=src_dir,
+        dest_dir=config.site_dir,
+        use_directory_urls=config.use_directory_urls
+    )
+    f.abs_src_path = src_path
+    return f

docs/plugins/filter_readmes.py

@@ -0,0 +1,35 @@
+import re
+
+from mkdocs.config.base import Config
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+
+def main(markdown: str, page: Page, config: Config, files: Files):
+    if page.title == "Charts":
+        return filter_repo_readme(markdown, page, config)
+    elif page.url.startswith("charts"):
+        return filter_chart_readme(markdown, page, config)
+
+
+def filter_repo_readme(markdown: str, page: Page, config: Config):
+    # Update page title
+    page.title = "Introduction"
+    markdown = markdown.split('\n', 1)[-1]
+    markdown = "# Introduction\n" + markdown
+
+    # Exclude chart overview from search
+    overview_re = re.compile(r"^(## Chart Overview)", re.MULTILINE)
+    markdown = overview_re.sub(r"\1 { data-search-exclude }", markdown)
+
+    return markdown
+
+
+def filter_chart_readme(markdown: str, page: Page, config: Config):
+    homepage_re = re.compile(r"^\*\*Homepage:\*\*.*$", re.MULTILINE)
+    markdown = homepage_re.sub("", markdown)
+
+    yaml_re = re.compile(r"\(\./(.*\.yaml)\)")
+    markdown = yaml_re.sub(f"({config.repo_url}/blob/main/{page.url}\\1)", markdown)
+
+    return markdown

docs/plugins/remove_sitemap_gz.py

@@ -0,0 +1,7 @@
+import os
+
+from mkdocs.config.base import Config
+
+
+def main(config: Config):
+    os.remove(os.path.join(config.site_dir, "sitemap.xml.gz"))

docs/requirements.txt

@@ -2,3 +2,4 @@ mkdocs==1.4.2
 mkdocs-material==9.1.3
 mkdocs-material-extensions==1.1.1
 mkdocs-minify-plugin==0.6.4
+mkdocs-simple-hooks==0.1.5