Auto class diagrams in the drunc docs

.github/workflows/deploy_docs_ghpage.yml

@@ -13,6 +13,10 @@ jobs:
     env: 
       WIKI_SUBFOLDER: Developer-Wiki
     steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: ts-graphviz/setup-graphviz@v1
       - name: Checkout Main Repository
         uses: actions/checkout@v5
 
@@ -25,6 +29,10 @@ jobs:
           # Create temporary wiki subfolder
           path: docs/${{ env.WIKI_SUBFOLDER }}
 
+      - name: Install daqpytools for uml generation
+        run : |
+          pip install "daqpytools[dev] @ git+https://github.com/DUNE-DAQ/daqpytools.git@develop"
+
       # Move Archives to a temp folder so they aren't processed
       - name: Hide Archive files from script
         run: |
@@ -43,6 +51,14 @@ jobs:
           python docs/utils/process_wiki.py $GITHUB_PAGES_BASE $WIKI_SUBFOLDER
           cd ~
 
+      - name: run uml generation
+        env:
+          PYTHONPATH: ${{ github.workspace }}/src
+        run: |
+          daqpytools-generate-uml drunc --directory . --output-directory pics --split
+          mkdir docs/class_diagrams
+          mv pics/split/classes_styled/*.png docs/class_diagrams
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

docs/__init__.py

@@ -0,0 +1 @@
+"""Docs package used for MkDocs macros."""

docs/gallery.md

@@ -0,0 +1,3 @@
+# Image Gallery
+
+{{ image_folder("class_diagrams", cols=4) }}

docs/gallery_generator.py

@@ -0,0 +1,92 @@
+"""
+Macro generator for image galleries in MkDocs.
+
+This module provides a macro that automatically renders all images from a folder
+as a responsive grid. It's used by mkdocs-macros-plugin.
+
+Usage in markdown:
+    {{ image_folder("img", cols=4) }}
+    {{ image_folder("assets/diagrams", cols=3) }}
+"""
+
+import html
+from pathlib import Path
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"}
+
+
+def define_env(env):
+    """
+    Define the image_folder macro for mkdocs-macros-plugin.
+
+    Args:
+        env: The mkdocs-macros environment object.
+    """
+
+    @env.macro
+    def image_folder(folder, cols=4):
+        """
+        Render a responsive image grid for a folder under docs/.
+
+        Automatically enumerates all image files in the folder and renders them
+        as a grid with captions from filenames. New images are picked up automatically
+        on rebuild without requiring markdown changes.
+
+        Usage:
+            {{ image_folder("img") }}                    # 4-column grid
+            {{ image_folder("assets/diagrams", cols=3) }} # 3-column grid
+
+        Args:
+            folder: Path relative to docs/ (e.g., "img" or "assets/generated-images")
+            cols:   Number of columns in the grid (default: 4)
+
+        Returns:
+            HTML string with grid of images, or error message if folder not found.
+        """
+        source_docs_dir = Path(__file__).resolve().parent
+        target_dir = (source_docs_dir / folder).resolve()
+
+        # Safety check: ensure folder is inside the source docs tree.
+        if source_docs_dir not in target_dir.parents and target_dir != source_docs_dir:
+            return f"<p><strong>Error:</strong> Image folder path is outside docs/: {html.escape(folder)}</p>"
+
+        if not target_dir.exists() or not target_dir.is_dir():
+            return (
+                f"<p><strong>Image folder not found:</strong> {html.escape(folder)}</p>"
+            )
+
+        # Collect all image files, sorted by name
+        files = sorted(
+            [
+                p
+                for p in target_dir.iterdir()
+                if p.is_file() and p.suffix.lower() in IMAGE_EXTS
+            ],
+            key=lambda p: p.name.lower(),
+        )
+
+        if not files:
+            return f"<p><em>No images found in {html.escape(folder)}</em></p>"
+
+        # Render HTML grid
+        col_style = f"repeat({int(cols)}, minmax(0, 1fr))"
+        out = [
+            f'<div class="image-folder-grid" style="grid-template-columns:{col_style};">'
+        ]
+
+        for p in files:
+            rel = f"{folder.rstrip('/')}/{p.name}"
+            page_rel = f"../{rel}"
+            caption = p.stem  # filename without extension
+
+            out.append(
+                "<figure>"
+                f'<a href="{html.escape(page_rel)}" target="_blank" rel="noopener">'
+                f'<img src="{html.escape(page_rel)}" loading="lazy" alt="{html.escape(caption)}">'
+                "</a>"
+                f"<figcaption>{html.escape(caption)}</figcaption>"
+                "</figure>"
+            )
+
+        out.append("</div>")
+        return "\n".join(out)

docs/requirements.txt

@@ -7,4 +7,5 @@ mkdocs-section-index
 mkdocstrings
 mkdocstrings-python
 pymdown-extensions
-mkdocs-exclude
+mkdocs-exclude
+mkdocs-macros-plugin

docs/stylesheets/gallery.css

@@ -0,0 +1,23 @@
+.image-folder-grid {
+  display: grid;
+  gap: 12px;
+  align-items: start;
+}
+
+.image-folder-grid figure {
+  margin: 0;
+}
+
+.image-folder-grid img {
+  width: 100%;
+  height: auto;
+  display: block;
+  border-radius: 6px;
+}
+
+.image-folder-grid figcaption {
+  font-size: 0.75rem;
+  opacity: 0.8;
+  margin-top: 6px;
+  word-break: break-word;
+}

mkdocs.yml

@@ -34,6 +34,8 @@ plugins:
   - exclude:
       glob:
         - Developer-Wiki/*
+  - macros:
+      module_name: docs/gallery_generator
   - gen-files:
       scripts:
         - docs/utils/generate_ghpages_docstrings.py
@@ -51,5 +53,8 @@ plugins:
             merge_init_into_class: true
           paths: [.]
 
+extra_css:
+  - stylesheets/gallery.css
+
 hooks:
 - docs/utils/mkdocs_hooks.py