Polish docs with common plugins and Mermaid diagrams

Author: nficano

.github/workflows/docs.yml

@@ -29,8 +29,12 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install mkdocs-material
-        run: pip install mkdocs-material
+      - name: Install docs dependencies
+        run: |
+          pip install \
+            mkdocs-material \
+            mkdocs-minify-plugin \
+            mkdocs-git-revision-date-localized-plugin
 
       - name: Build site
         run: mkdocs build --strict

docs/architecture.md

@@ -10,22 +10,35 @@ pools**. Each pool maps to a `[[runners]]` entry in the config file and
 operates independently with its own executor type, concurrency level, and
 GitHub API credentials.
 
-```
-┌─────────────────────────────────────────────────┐
-│                   CLI (cobra)                    │
-├─────────────────────────────────────────────────┤
-│              Runner Manager (1 per process)      │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
-│  │ Worker 1 │ │ Worker 2 │ │ Worker N │  ...    │
-│  │ (Job)    │ │ (Idle)   │ │ (Job)    │        │
-│  └──────────┘ └──────────┘ └──────────┘        │
-├─────────────────────────────────────────────────┤
-│  Executor Layer   │  Cache Layer  │  Artifact   │
-│  (shell/docker/   │  (local/s3/   │  Manager    │
-│   k8s/firecracker)│   gcs)        │             │
-├─────────────────────────────────────────────────┤
-│  GitHub API Client │ Metrics │ Health │ Logger   │
-└─────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+    CLI["CLI (cobra)"] --> Manager["Runner Manager (1 per process)"]
+
+    subgraph Pools["Runner pools (one per [[runners]] entry)"]
+      W1["Worker 1 (job)"]
+      W2["Worker 2 (idle)"]
+      WN["Worker N (job)"]
+    end
+
+    Manager --> Pools
+
+    subgraph Layers["Execution + services"]
+      Executor["Executor layer<br/>shell / docker / kubernetes / firecracker"]
+      Cache["Cache layer<br/>local / s3 / gcs"]
+      Artifact["Artifact manager"]
+      GitHubAPI["GitHub API client"]
+      Metrics["Metrics"]
+      Health["Health"]
+      Logger["Logger"]
+    end
+
+    Pools --> Executor
+    Pools --> Cache
+    Pools --> Artifact
+    Manager --> GitHubAPI
+    Manager --> Metrics
+    Manager --> Health
+    Manager --> Logger
 ```
 
 ## Component diagram
@@ -203,23 +216,25 @@ If shutdown_timeout expires:
 
 ## Data flow: job lifecycle
 
-```
-GitHub API                    Runner                         Executor
-    │                           │                               │
-    │◄── poll (GET /jobs) ──────│                               │
-    │── job payload ───────────►│                               │
-    │                           │── Prepare() ─────────────────►│
-    │◄── status: in_progress ───│                               │
-    │                           │── Run(step 1) ───────────────►│
-    │◄── heartbeat ─────────────│                               │
-    │◄── step status ───────────│◄── StepResult ────────────────│
-    │                           │── Run(step 2) ───────────────►│
-    │◄── heartbeat ─────────────│                               │
-    │◄── step status ───────────│◄── StepResult ────────────────│
-    │                           │                               │
-    │◄── status: completed ─────│                               │
-    │                           │── Cleanup() ─────────────────►│
-    │                           │                               │
+```mermaid
+sequenceDiagram
+    participant GH as GitHub API
+    participant R as Runner
+    participant E as Executor
+
+    R->>GH: Poll jobs (GET /jobs)
+    GH-->>R: Job payload
+    R->>E: Prepare()
+    R->>GH: Status in_progress
+
+    loop For each workflow step
+      R->>E: Run(step)
+      E-->>R: StepResult
+      R->>GH: Step status + heartbeat
+    end
+
+    R->>GH: Status completed
+    R->>E: Cleanup()
 ```
 
 ## Package dependency graph

docs/javascripts/mermaid.js

@@ -0,0 +1,19 @@
+const renderMermaid = () => {
+  if (!window.mermaid) {
+    return;
+  }
+
+  window.mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "loose",
+    theme: "neutral",
+  });
+
+  window.mermaid.run({ querySelector: ".mermaid" });
+};
+
+if (typeof document$ !== "undefined") {
+  document$.subscribe(renderMermaid);
+} else {
+  window.addEventListener("load", renderMermaid);
+}

docs/stylesheets/extra.css

@@ -0,0 +1,19 @@
+:root {
+  --runner-matte-black: #141414;
+}
+
+[data-md-color-scheme="default"] .md-header,
+[data-md-color-scheme="default"] .md-tabs,
+[data-md-color-scheme="slate"] .md-header,
+[data-md-color-scheme="slate"] .md-tabs {
+  background-color: var(--runner-matte-black);
+}
+
+[data-md-color-scheme="default"] .md-tabs__link--active,
+[data-md-color-scheme="default"] .md-tabs__link:focus,
+[data-md-color-scheme="default"] .md-tabs__link:hover,
+[data-md-color-scheme="slate"] .md-tabs__link--active,
+[data-md-color-scheme="slate"] .md-tabs__link:focus,
+[data-md-color-scheme="slate"] .md-tabs__link:hover {
+  color: #ffd54f;
+}

mkdocs.yml

@@ -26,20 +26,40 @@ theme:
         icon: material/weather-sunny
         name: Switch to light mode
   features:
+    - content.action.edit
+    - content.code.annotate
     - content.code.copy
     - navigation.tabs
     - navigation.instant
     - navigation.sections
     - navigation.expand
     - navigation.top
+    - navigation.footer
     - search.highlight
     - toc.follow
 
+plugins:
+  - search
+  - minify:
+      minify_html: true
+  - git-revision-date-localized:
+      type: timeago
+      enable_creation_date: true
+      fallback_to_build_date: true
+
 markdown_extensions:
   - tables
+  - attr_list
+  - md_in_html
+  - def_list
+  - footnotes
   - admonition
+  - pymdownx.details
   - pymdownx.highlight:
       anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.snippets
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -52,6 +72,13 @@ markdown_extensions:
   - toc:
       permalink: true
 
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - https://unpkg.com/mermaid@10.9.1/dist/mermaid.min.js
+  - javascripts/mermaid.js
+
 nav:
   - Home: index.md
   - Architecture: architecture.md