mkdocs-terok 0.5.6__py3-none-any.whl

mkdocs_terok/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: 0BSD
+
+"""Shared ProperDocs documentation generators for terok projects.
+
+Provides reusable modules for CI maps, test maps, quality reports,
+API reference pages, and Pydantic config reference rendering.
+The ``terok`` ProperDocs plugin wraps all generators; individual modules
+remain usable standalone (they never import properdocs themselves).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__version__ = "0.5.6"  # managed by poetry-dynamic-versioning
+
+
+def brand_css_path() -> Path:
+    """Return the filesystem path to the shared brand CSS file."""
+    return Path(__file__).parent / "_assets" / "extra.css"
+
+
+def mermaid_zoom_js_path() -> Path:
+    """Return the filesystem path to the Mermaid diagram zoom script."""
+    return Path(__file__).parent / "_assets" / "mermaid_zoom.js"

mkdocs_terok/_assets/extra.css

@@ -0,0 +1,211 @@
+/* Black/Red/Gold palette with subdued neutrals. */
+:root {
+  --terok-black: #0b0b0b;
+  --terok-red: #a31219;
+  --terok-red-dark: #7f0f14;
+  --terok-red-pure: #c00000;
+  --terok-red-bright: #e04b3f;
+  --terok-gold: #c79a22;
+  --terok-gold-bright: #d8b454;
+  --terok-gold-link: #7a6200;
+  --terok-red-hover: #8b0000;
+
+  --md-text-font: "Ubuntu", sans-serif;
+  --md-code-font: "Ubuntu Mono", monospace;
+
+  --md-primary-fg-color: var(--terok-red-dark);
+  --md-primary-fg-color--light: #8f1117;
+  --md-primary-fg-color--dark: #650b10;
+
+  --md-primary-bg-color: #f7f2e8;
+  --md-primary-bg-color--light: #f7f2e8;
+  --md-primary-bg-color--dark: #e7decc;
+
+  --md-accent-fg-color: var(--terok-gold);
+  --md-accent-fg-color--transparent: rgba(199, 154, 34, 0.12);
+
+  --md-typeset-a-color: var(--terok-gold-link);
+  --md-typeset-mark-color: var(--terok-gold-bright);
+}
+
+body,
+.md-typeset,
+.md-header,
+.md-tabs,
+.md-nav,
+.md-search__input {
+  font-family: var(--md-text-font);
+}
+
+pre,
+code,
+kbd,
+samp {
+  font-family: var(--md-code-font);
+}
+
+.md-header,
+.md-tabs,
+.md-header__inner,
+.md-tabs__inner {
+  background-color: var(--terok-red-dark) !important;
+}
+
+.md-typeset a,
+.md-typeset a:visited {
+  color: var(--terok-gold-link);
+}
+
+.md-typeset a:hover,
+.md-nav__link:hover,
+.md-tabs__link:hover,
+.md-header__button:hover {
+  color: var(--terok-red-hover) !important;
+}
+
+.md-nav__item--active > .md-nav__link,
+.md-nav__link--active,
+.md-nav--secondary .md-nav__link--active {
+  color: var(--terok-gold-bright) !important;
+}
+
+.md-nav--secondary .md-nav__link--active::before,
+.md-nav--secondary .md-nav__link--active::after {
+  background-color: var(--terok-gold-bright);
+}
+
+.md-nav--secondary .md-nav__link--active {
+  border-left-color: var(--terok-gold-bright);
+}
+
+.md-tabs__link--active {
+  color: inherit !important;
+  font-weight: 700;
+}
+
+#codecov-treemap-img {
+  display: block;
+  min-width: 300px;
+  width: 60%;
+  margin: 0 auto;
+}
+
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: var(--terok-red-dark);
+  --md-primary-fg-color--light: #8f1117;
+  --md-primary-fg-color--dark: #650b10;
+  --md-default-bg-color: #f7f2e8;
+  --md-default-fg-color: #111111;
+  --md-default-fg-color--light: #2b2b2b;
+  --md-default-fg-color--lighter: #4a4a4a;
+  --md-default-fg-color--lightest: #6a6a6a;
+  --md-code-bg-color: #efe6d6;
+  --md-code-fg-color: #111111;
+  --md-footer-bg-color: #0b0b0b;
+  --md-footer-fg-color: #f7f2e8;
+  --md-footer-fg-color--light: #d9cfbd;
+  --md-footer-fg-color--lighter: #bdb39f;
+  --md-footer-fg-color--lightest: #a79c87;
+  --md-accent-fg-color: var(--terok-gold);
+  --md-accent-fg-color--transparent: rgba(199, 154, 34, 0.12);
+  --md-typeset-a-color: var(--terok-gold-link);
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: var(--terok-red-dark);
+  --md-primary-fg-color--light: #8f1117;
+  --md-primary-fg-color--dark: #650b10;
+  --md-default-bg-color: #0b0b0b;
+  --md-default-fg-color: #f2ead9;
+  --md-default-fg-color--light: #d8cfbf;
+  --md-default-fg-color--lighter: #bcb4a5;
+  --md-default-fg-color--lightest: #a19a8d;
+  --md-code-bg-color: #151515;
+  --md-code-fg-color: #f2ead9;
+  --md-footer-bg-color: #000000;
+  --md-footer-fg-color: #f2ead9;
+  --md-footer-fg-color--light: #d8cfbf;
+  --md-footer-fg-color--lighter: #bcb4a5;
+  --md-footer-fg-color--lightest: #a19a8d;
+
+  --md-primary-bg-color: #f2ead9;
+  --md-primary-bg-color--light: #f2ead9;
+  --md-primary-bg-color--dark: #d8cfbf;
+
+  --md-accent-fg-color: var(--terok-gold-bright);
+  --md-accent-fg-color--transparent: rgba(216, 180, 84, 0.14);
+  --md-typeset-a-color: var(--terok-gold-bright);
+}
+
+/* ── Mermaid diagram zoom overlay ───────────────────────────── */
+.mermaid-zoom-wrapper {
+  position: relative;
+}
+
+.mermaid-zoom-btn {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  z-index: 1;
+  padding: 2px 8px;
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 4px;
+  background: var(--md-default-bg-color);
+  color: var(--md-default-fg-color--light);
+  font: 0.7rem var(--md-text-font);
+  cursor: pointer;
+}
+
+.mermaid-zoom-overlay {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  background: rgba(0, 0, 0, 0.75);
+  backdrop-filter: blur(4px);
+}
+
+.mermaid-zoom-overlay.mermaid-zoom-active {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mermaid-zoom-viewport {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: calc(100vw - 4rem);
+  height: calc(100vh - 4rem);
+  padding: 1rem;
+  border-radius: 8px;
+  background: var(--md-default-bg-color);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  overflow: auto;
+}
+
+.mermaid-zoom-viewport svg {
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.mermaid-zoom-close {
+  position: absolute;
+  top: 0.75rem;
+  right: 0.75rem;
+  z-index: 10000;
+  width: 2rem;
+  height: 2rem;
+  border: none;
+  border-radius: 50%;
+  background: var(--terok-red-dark);
+  color: #fff;
+  font-size: 1.1rem;
+  line-height: 1;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.mermaid-zoom-close:hover {
+  background: var(--terok-red);
+}

mkdocs_terok/_assets/mermaid_zoom.js

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+// SPDX-License-Identifier: 0BSD
+
+/**
+ * Adds an "Enlarge" button to each rendered Mermaid diagram.
+ * Clicking it opens the diagram in a fullscreen overlay (lightbox-style).
+ * Close via backdrop click, the X button, or Escape.
+ */
+;(() => {
+  const BUTTON_LABEL = "\u2922 Enlarge"
+
+  // ── Main action ────────────────────────────────────────
+
+  /** Scan the DOM for rendered mermaid SVGs and attach buttons. */
+  function scan() {
+    document.querySelectorAll("pre.mermaid, .mermaid").forEach((el) => {
+      if (el.querySelector("svg") || el.tagName === "SVG") attachButton(el)
+    })
+  }
+
+  /** Wrap a rendered mermaid container and inject the enlarge button. */
+  function attachButton(container) {
+    if (container.dataset.zoomAttached) return
+    container.dataset.zoomAttached = "1"
+
+    const wrapper = document.createElement("div")
+    wrapper.className = "mermaid-zoom-wrapper"
+    container.parentNode.insertBefore(wrapper, container)
+    wrapper.appendChild(container)
+
+    const btn = document.createElement("button")
+    btn.className = "mermaid-zoom-btn"
+    btn.textContent = BUTTON_LABEL
+    btn.addEventListener("click", () => {
+      openOverlay(container.querySelector("svg") ?? container)
+    })
+    container.before(btn)
+  }
+
+  // ── Overlay mechanics ──────────────────────────────────
+
+  function openOverlay(svgSource) {
+    const overlay =
+      document.querySelector(".mermaid-zoom-overlay") || createOverlay()
+    const viewport = overlay.querySelector(".mermaid-zoom-viewport")
+    viewport.innerHTML = ""
+    const clone = svgSource.cloneNode(true)
+    clone.removeAttribute("height")
+    clone.removeAttribute("width")
+    clone.style.maxWidth = "100%"
+    clone.style.maxHeight = "100%"
+    clone.style.width = "auto"
+    clone.style.height = "auto"
+    viewport.appendChild(clone)
+    overlay.classList.add("mermaid-zoom-active")
+    document.addEventListener("keydown", onEscape)
+  }
+
+  function closeOverlay(overlay) {
+    overlay.classList.remove("mermaid-zoom-active")
+    document.removeEventListener("keydown", onEscape)
+  }
+
+  function onEscape(e) {
+    if (e.key === "Escape") {
+      const overlay = document.querySelector(".mermaid-zoom-overlay")
+      if (overlay) closeOverlay(overlay)
+    }
+  }
+
+  /** Build the overlay element (singleton, appended on first use). */
+  function createOverlay() {
+    const overlay = document.createElement("div")
+    overlay.className = "mermaid-zoom-overlay"
+    overlay.addEventListener("click", (e) => {
+      if (e.target === overlay) closeOverlay(overlay)
+    })
+
+    const close = document.createElement("button")
+    close.className = "mermaid-zoom-close"
+    close.textContent = "\u2715"
+    close.title = "Close"
+    close.addEventListener("click", () => closeOverlay(overlay))
+
+    const viewport = document.createElement("div")
+    viewport.className = "mermaid-zoom-viewport"
+
+    overlay.append(close, viewport)
+    document.body.appendChild(overlay)
+    return overlay
+  }
+
+  // ── Initialization ─────────────────────────────────────
+
+  // Initial scan once DOM + mermaid rendering settle.
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => setTimeout(scan, 2000))
+  } else {
+    setTimeout(scan, 2000)
+  }
+
+  // Catch diagrams rendered after initial load (e.g. instant navigation).
+  const observer = new MutationObserver((mutations) => {
+    for (const m of mutations) {
+      for (const node of m.addedNodes) {
+        if (node.nodeType !== 1) continue
+        if (
+          (node.matches?.(".mermaid, pre.mermaid") && node.querySelector("svg")) ||
+          node.querySelector?.(".mermaid svg, pre.mermaid svg") ||
+          (node.tagName === "svg" && node.parentElement?.matches?.(".mermaid, pre.mermaid"))
+        ) {
+          setTimeout(scan, 200)
+          return
+        }
+      }
+    }
+  })
+
+  function startObserver() {
+    observer.observe(document.body, { childList: true, subtree: true })
+  }
+
+  if (document.body) {
+    startObserver()
+  } else {
+    document.addEventListener("DOMContentLoaded", startObserver, { once: true })
+  }
+})()

mkdocs_terok/ci_map.py

@@ -0,0 +1,174 @@
+# SPDX-FileCopyrightText: 2026 Jiri Vyskocil
+# SPDX-License-Identifier: 0BSD
+
+"""Generate a Markdown map of GitHub workflows and jobs.
+
+Parses ``.github/workflows/*.yml`` and ``.yaml`` files and produces a
+Markdown document with workflow summary and per-job detail tables.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+
+# ── Entry point ─────────────────────────────────────────
+
+
+def generate_ci_map(
+    workflows: list[dict[str, object]] | None = None,
+    *,
+    workflows_dir: Path | None = None,
+) -> str:
+    """Generate the Markdown CI map.
+
+    Args:
+        workflows: Pre-loaded workflow data. If ``None``, loads from disk.
+        workflows_dir: Override for the workflows directory.
+    """
+    if workflows is None:
+        workflows = load_workflows(workflows_dir)
+    job_count = sum(len(workflow["jobs"]) for workflow in workflows)
+    now = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
+
+    lines = [
+        "# CI Workflow Map\n\n",
+        f"*Generated: {now}*\n\n",
+        f"**{len(workflows)} workflows** with **{job_count} jobs**\n\n",
+        "## Workflows\n\n",
+        "| Workflow | File | Triggers | Jobs |\n",
+        "|---|---|---|---|\n",
+    ]
+    for workflow in workflows:
+        lines.append(
+            f"| `{workflow['name']}` | `{workflow['file_name']}` | "
+            f"{workflow['triggers']} | {len(workflow['jobs'])} |\n"
+        )
+
+    lines.extend(
+        [
+            "\n## Jobs\n\n",
+            "| Workflow | Job | Needs | Uploads | Downloads |\n",
+            "|---|---|---|---|---|\n",
+        ]
+    )
+    for workflow in workflows:
+        for job in workflow["jobs"]:
+            lines.append(
+                f"| `{workflow['name']}` | `{job['name']}` | {_render(job['needs'])} | "
+                f"{_render(job['uploads'])} | {_render(job['downloads'])} |\n"
+            )
+
+    lines.append("\n")
+    return "".join(lines)
+
+
+# ── Workflow loading ────────────────────────────────────
+
+
+def load_workflows(workflows_dir: Path | None = None) -> list[dict[str, object]]:
+    """Load workflow and job facts from ``.github/workflows/*.yml``.
+
+    Args:
+        workflows_dir: Directory containing workflow YAML files.
+            Defaults to ``.github/workflows/`` relative to cwd.
+    """
+    if workflows_dir is None:
+        workflows_dir = Path.cwd() / ".github" / "workflows"
+    workflows: list[dict[str, object]] = []
+    yml_files = list(workflows_dir.glob("*.yml")) + list(workflows_dir.glob("*.yaml"))
+    for path in sorted(yml_files):
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        if not isinstance(data, dict):
+            continue
+
+        jobs: list[dict[str, object]] = []
+        jobs_section = data.get("jobs", {})
+        if isinstance(jobs_section, dict):
+            for job_id, job_data in jobs_section.items():
+                if not isinstance(job_data, dict):
+                    continue
+                needs = job_data.get("needs", ())
+                needs_tuple = (
+                    (needs,)
+                    if isinstance(needs, str)
+                    else tuple(str(item) for item in needs)
+                    if isinstance(needs, list)
+                    else ()
+                )
+                jobs.append(
+                    {
+                        "name": str(job_data.get("name", job_id)),
+                        "needs": needs_tuple,
+                        "uploads": _artifact_names(
+                            job_data.get("steps"), "actions/upload-artifact"
+                        ),
+                        "downloads": _artifact_names(
+                            job_data.get("steps"), "actions/download-artifact"
+                        ),
+                    }
+                )
+
+        workflows.append(
+            {
+                "file_name": path.name,
+                "name": str(data.get("name", path.stem)),
+                "triggers": _trigger_summary(data),
+                "jobs": jobs,
+            }
+        )
+    return workflows
+
+
+# ── Formatting helpers ──────────────────────────────────
+
+
+def _artifact_names(steps: object, prefix: str) -> tuple[str, ...]:
+    """Collect upload/download artifact names from a list of steps."""
+    if not isinstance(steps, list):
+        return ()
+    names: list[str] = []
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        uses = step.get("uses")
+        if not isinstance(uses, str) or not uses.startswith(prefix):
+            continue
+        with_section = step.get("with", {})
+        if isinstance(with_section, dict):
+            name = with_section.get("name")
+            names.append(str(name) if name else "(all artifacts)")
+    return tuple(names)
+
+
+def _trigger_summary(data: dict[object, object]) -> str:
+    """Render the top-level ``on`` section as a compact string."""
+    on_section = data.get("on", data.get(True, {}))
+    if isinstance(on_section, str):
+        return f"`{on_section}`"
+    if isinstance(on_section, list):
+        return ", ".join(f"`{item}`" for item in on_section)
+    if not isinstance(on_section, dict):
+        return "—"
+
+    parts: list[str] = []
+    for name, value in on_section.items():
+        suffix = ""
+        if isinstance(value, dict):
+            if name in {"push", "pull_request", "pull_request_target"}:
+                branches = value.get("branches")
+                if isinstance(branches, list) and branches:
+                    suffix = f"({', '.join(str(branch) for branch in branches)})"
+            elif name == "workflow_run":
+                workflows = value.get("workflows")
+                if isinstance(workflows, list) and workflows:
+                    suffix = f"({', '.join(str(workflow) for workflow in workflows)})"
+        parts.append(f"`{name}{suffix}`")
+    return ", ".join(parts) if parts else "—"
+
+
+def _render(values: tuple[str, ...]) -> str:
+    """Render a tuple of values into one Markdown table cell."""
+    return "<br>".join(f"`{value}`" for value in values) if values else "—"