docrev 0.10.0 → 0.10.2

package/docs-src/build.py

@@ -1,113 +1,113 @@
-#!/usr/bin/env python3
-"""
-Build the docrev documentation site using pandoc + Bootstrap 5 Sandstone.
-
-Usage (from project root):
-    python docs-src/build.py           # build to site/
-    python docs-src/build.py --serve   # build + open index.html
-    python docs-src/build.py --deploy  # build + push to gh-pages
-"""
-
-import argparse
-import json
-import shutil
-import subprocess
-import sys
-import webbrowser
-from pathlib import Path
-
-HERE        = Path(__file__).parent          # docs-src/
-PROJECT     = HERE.parent                    # project root
-DOCS        = PROJECT / "docs"
-SITE        = PROJECT / "site"
-TEMPLATE    = HERE / "template.html"
-EXTRA_CSS   = HERE / "extra.css"
-LUA_FILTER  = HERE / "md-to-html.lua"
-
-PAGES = [
-    # (source md,          output html,            page title,      active-key,              toc)
-    ("index.md",          "index.html",          "Home",          "active-home",           False),
-    ("workflow.md",       "workflow.html",       "Get Started",   "active-workflow",       True),
-    ("commands.md",       "commands.html",       "Commands",      "active-commands",       True),
-    ("configuration.md",  "configuration.html",  "Configuration", "active-configuration",  True),
-    ("troubleshooting.md","troubleshooting.html","Troubleshooting","active-troubleshooting",True),
-]
-
-
-def get_version() -> str:
-    pkg = PROJECT / "package.json"
-    if pkg.exists():
-        return json.loads(pkg.read_text())["version"]
-    return ""
-
-
-def build_page(md_name, html_name, title, active_key, use_toc, version):
-    src = DOCS / md_name
-    dst = SITE / html_name
-
-    cmd = [
-        "pandoc", str(src),
-        "--template", str(TEMPLATE),
-        "--to", "html5",
-        "--from", "markdown+smart+definition_lists",
-        "--highlight-style", "pygments",
-        "--lua-filter", str(LUA_FILTER),
-        "--metadata", f"title={title}",
-        "--metadata", f"pagetitle={title}",
-        "--metadata", f"version={version}",
-        "--metadata", f"{active_key}=true",
-        "--output", str(dst),
-    ]
-
-    if use_toc:
-        cmd += ["--toc", "--toc-depth=3"]
-
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    if result.returncode != 0:
-        print(f"  ERROR: {md_name}")
-        print(result.stderr)
-        return False
-
-    print(f"  {html_name}")
-    return True
-
-
-def build(deploy=False, serve=False):
-    if SITE.exists():
-        shutil.rmtree(SITE)
-    SITE.mkdir()
-    assets = SITE / "assets"
-    assets.mkdir()
-
-    shutil.copy(EXTRA_CSS, assets / "extra.css")
-
-    version = get_version()
-    print(f"Building docrev {version} → site/")
-
-    ok = all(build_page(*p, version) for p in PAGES)
-
-    if not ok:
-        sys.exit(1)
-
-    print("Done.")
-
-    if serve:
-        webbrowser.open(str(SITE / "index.html"))
-
-    if deploy:
-        print("\nDeploying to gh-pages …")
-        result = subprocess.run(
-            ["python", "-m", "ghp_import", "-n", "-p", "-f", str(SITE)],
-            cwd=PROJECT,
-        )
-        if result.returncode != 0:
-            sys.exit(result.returncode)
-        print("Deployed.")
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--serve",  action="store_true", help="Open index.html after build")
-    parser.add_argument("--deploy", action="store_true", help="Push site/ to gh-pages")
-    args = parser.parse_args()
-    build(deploy=args.deploy, serve=args.serve)
+#!/usr/bin/env python3
+"""
+Build the docrev documentation site using pandoc + Bootstrap 5 Sandstone.
+
+Usage (from project root):
+    python docs-src/build.py           # build to site/
+    python docs-src/build.py --serve   # build + open index.html
+    python docs-src/build.py --deploy  # build + push to gh-pages
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import webbrowser
+from pathlib import Path
+
+HERE        = Path(__file__).parent          # docs-src/
+PROJECT     = HERE.parent                    # project root
+DOCS        = PROJECT / "docs"
+SITE        = PROJECT / "site"
+TEMPLATE    = HERE / "template.html"
+EXTRA_CSS   = HERE / "extra.css"
+LUA_FILTER  = HERE / "md-to-html.lua"
+
+PAGES = [
+    # (source md,          output html,            page title,      active-key,              toc)
+    ("index.md",          "index.html",          "Home",          "active-home",           False),
+    ("workflow.md",       "workflow.html",       "Get Started",   "active-workflow",       True),
+    ("commands.md",       "commands.html",       "Commands",      "active-commands",       True),
+    ("configuration.md",  "configuration.html",  "Configuration", "active-configuration",  True),
+    ("troubleshooting.md","troubleshooting.html","Troubleshooting","active-troubleshooting",True),
+]
+
+
+def get_version() -> str:
+    pkg = PROJECT / "package.json"
+    if pkg.exists():
+        return json.loads(pkg.read_text())["version"]
+    return ""
+
+
+def build_page(md_name, html_name, title, active_key, use_toc, version):
+    src = DOCS / md_name
+    dst = SITE / html_name
+
+    cmd = [
+        "pandoc", str(src),
+        "--template", str(TEMPLATE),
+        "--to", "html5",
+        "--from", "markdown+smart+definition_lists",
+        "--highlight-style", "pygments",
+        "--lua-filter", str(LUA_FILTER),
+        "--metadata", f"title={title}",
+        "--metadata", f"pagetitle={title}",
+        "--metadata", f"version={version}",
+        "--metadata", f"{active_key}=true",
+        "--output", str(dst),
+    ]
+
+    if use_toc:
+        cmd += ["--toc", "--toc-depth=3"]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"  ERROR: {md_name}")
+        print(result.stderr)
+        return False
+
+    print(f"  {html_name}")
+    return True
+
+
+def build(deploy=False, serve=False):
+    if SITE.exists():
+        shutil.rmtree(SITE)
+    SITE.mkdir()
+    assets = SITE / "assets"
+    assets.mkdir()
+
+    shutil.copy(EXTRA_CSS, assets / "extra.css")
+
+    version = get_version()
+    print(f"Building docrev {version} → site/")
+
+    ok = all(build_page(*p, version) for p in PAGES)
+
+    if not ok:
+        sys.exit(1)
+
+    print("Done.")
+
+    if serve:
+        webbrowser.open(str(SITE / "index.html"))
+
+    if deploy:
+        print("\nDeploying to gh-pages …")
+        result = subprocess.run(
+            ["python", "-m", "ghp_import", "-n", "-p", "-f", str(SITE)],
+            cwd=PROJECT,
+        )
+        if result.returncode != 0:
+            sys.exit(result.returncode)
+        print("Deployed.")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serve",  action="store_true", help="Open index.html after build")
+    parser.add_argument("--deploy", action="store_true", help="Push site/ to gh-pages")
+    args = parser.parse_args()
+    build(deploy=args.deploy, serve=args.serve)

package/docs-src/extra.css

@@ -1,208 +1,208 @@
-/* ── Base ──────────────────────────────────────────────── */
-html, body {
-  height: 100%;
-}
-
-body {
-  background-color: #F5F6F8;
-  color: #3E3F3A;
-  display: flex;
-  flex-direction: column;
-  min-height: 100vh;
-  padding-top: 4rem;
-  font-family: "Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
-}
-
-.container { flex: 1; }
-footer { margin-top: auto; }
-
-/* ── Navbar (pkgdown-style subtle tint, not bg-primary) ── */
-.navbar {
-  background: color-mix(in oklab, color-mix(in oklab, var(--bs-body-bg) 95%, var(--bs-primary)) 95%, var(--bs-body-color));
-  border-bottom: 1px solid #DFD7CA;
-  line-height: initial;
-}
-
-.navbar .nav-link.active {
-  font-weight: 600;
-  color: var(--bs-primary) !important;
-}
-
-/* ── Links ─────────────────────────────────────────────── */
-a { color: #325D88; }
-a:hover { color: #1E3D5C; }
-
-/* ── Headings ──────────────────────────────────────────── */
-h1 { font-size: 2rem; font-weight: 600; margin-bottom: 1rem; }
-h2 {
-  font-size: 1.4rem; font-weight: 600;
-  margin-top: 2rem; margin-bottom: .65rem;
-  padding-bottom: .3rem;
-  border-bottom: 1px solid #DFD7CA;
-}
-h3 { font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; }
-h4 { font-size: 1rem;   font-weight: 600; margin-top: 1.2rem; }
-
-/* ── Code ──────────────────────────────────────────────── */
-pre, div.sourceCode {
-  background-color: #EEEEED;
-  border: 1px solid #DFD7CA;
-  border-radius: .375rem;
-  padding: .9rem 1.1rem;
-  font-size: .85rem;
-  overflow-x: auto;
-  margin: 1em 0;
-}
-
-code {
-  background-color: #EEEEED;
-  color: #3E3F3A;
-  border-radius: .25rem;
-  padding: .1em .35em;
-  font-size: .875em;
-}
-
-pre code, div.sourceCode code {
-  background: none;
-  padding: 0;
-  border-radius: 0;
-  font-size: inherit;
-  color: inherit;
-}
-
-div.sourceCode { padding: 0; }
-div.sourceCode pre { border: none; margin: 0; }
-
-/* ── Tables ────────────────────────────────────────────── */
-table {
-  width: 100%;
-  border-collapse: collapse;
-  margin: 1em 0;
-  font-size: .9rem;
-}
-
-thead th {
-  background-color: #DFD7CA;
-  color: #3E3F3A;
-  font-weight: 600;
-  padding: .5rem .75rem;
-  border-bottom: 2px solid #c8c0b4;
-  text-align: left;
-}
-
-td, th { padding: .4rem .75rem; border-bottom: 1px solid #e8e2d8; }
-tbody tr:hover { background-color: rgba(223,215,202,.2); }
-
-/* ── TOC sidebar ───────────────────────────────────────── */
-aside#toc, aside .toc, aside nav.toc { font-size: .875rem; }
-
-aside h2.h6 {
-  text-transform: uppercase;
-  font-size: .68rem;
-  letter-spacing: .07em;
-  color: #6c757d;
-  font-weight: 600;
-  margin-bottom: .5rem;
-  border: none;
-  padding: 0;
-}
-
-aside .toc, aside #TOC {
-  position: sticky;
-  top: 5rem;
-  max-height: calc(100vh - 6rem);
-  overflow-y: auto;
-}
-
-aside ul {
-  list-style: none;
-  padding-left: .9rem;
-  margin: 0;
-}
-aside > nav > .toc > ul,
-aside .toc > ul { padding-left: 0; }
-
-aside li { margin: .1rem 0; }
-
-aside a {
-  color: #6c757d;
-  text-decoration: none;
-  display: block;
-  line-height: 1.55;
-}
-aside a:hover { color: #325D88; }
-
-/* ── Home page cards ───────────────────────────────────── */
-.doc-card {
-  border: 1px solid #DFD7CA;
-  border-radius: .375rem;
-  padding: 1.1rem 1.25rem;
-  height: 100%;
-  background: #fff;
-  transition: border-color .15s, box-shadow .15s;
-}
-.doc-card:hover {
-  border-color: #325D88;
-  box-shadow: 0 2px 8px rgba(50,93,136,.1);
-}
-.doc-card h5 { font-size: 1rem; font-weight: 600; margin-bottom: .4rem; }
-.doc-card p  { font-size: .875rem; color: #6c757d; margin-bottom: .6rem; }
-.doc-card a.stretched-link::after { z-index: 1; }
-
-/* ── Badges row ────────────────────────────────────────── */
-.badge-row { margin-bottom: 1rem; line-height: 2; }
-.badge-row img { margin-right: .25rem; }
-
-/* ── ── ── DARK MODE ── ── ── ──────────────────────────── */
-
-[data-bs-theme="dark"] body  { background-color: #343739; color: #DFD7CA; }
-
-[data-bs-theme="dark"] .navbar {
-  background: color-mix(in oklab, color-mix(in oklab, #343739 92%, var(--bs-primary)) 95%, #DFD7CA);
-  border-bottom-color: #495057;
-}
-
-[data-bs-theme="dark"] a       { color: #7ba8d0; }
-[data-bs-theme="dark"] a:hover { color: #a5c4e8; }
-
-[data-bs-theme="dark"] .navbar .nav-link.active { color: #7ba8d0 !important; }
-
-[data-bs-theme="dark"] h1,
-[data-bs-theme="dark"] h2,
-[data-bs-theme="dark"] h3,
-[data-bs-theme="dark"] h4 { color: #DFD7CA; }
-
-[data-bs-theme="dark"] h2 { border-color: #495057; }
-
-[data-bs-theme="dark"] pre,
-[data-bs-theme="dark"] div.sourceCode {
-  background-color: #2C2F31;
-  border-color: #495057;
-  color: #DFD7CA;
-}
-
-[data-bs-theme="dark"] code {
-  background-color: #2C2F31;
-  color: #DFD7CA;
-}
-
-[data-bs-theme="dark"] div.sourceCode span[class] { color: #DFD7CA !important; }
-
-[data-bs-theme="dark"] thead th {
-  background-color: #3d4043;
-  color: #DFD7CA;
-  border-color: #495057;
-}
-[data-bs-theme="dark"] td,
-[data-bs-theme="dark"] th  { border-color: #3d4043; }
-[data-bs-theme="dark"] tbody tr:hover { background-color: rgba(73,80,87,.3); }
-
-[data-bs-theme="dark"] aside a       { color: #8e9499; }
-[data-bs-theme="dark"] aside a:hover { color: #7ba8d0; }
-
-[data-bs-theme="dark"] .doc-card {
-  background: #2C2F31;
-  border-color: #495057;
-}
-[data-bs-theme="dark"] .doc-card:hover { border-color: #7ba8d0; }
-[data-bs-theme="dark"] .doc-card p     { color: #8e9499; }
+/* ── Base ──────────────────────────────────────────────── */
+html, body {
+  height: 100%;
+}
+
+body {
+  background-color: #F5F6F8;
+  color: #3E3F3A;
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  padding-top: 4rem;
+  font-family: "Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+}
+
+.container { flex: 1; }
+footer { margin-top: auto; }
+
+/* ── Navbar (pkgdown-style subtle tint, not bg-primary) ── */
+.navbar {
+  background: color-mix(in oklab, color-mix(in oklab, var(--bs-body-bg) 95%, var(--bs-primary)) 95%, var(--bs-body-color));
+  border-bottom: 1px solid #DFD7CA;
+  line-height: initial;
+}
+
+.navbar .nav-link.active {
+  font-weight: 600;
+  color: var(--bs-primary) !important;
+}
+
+/* ── Links ─────────────────────────────────────────────── */
+a { color: #325D88; }
+a:hover { color: #1E3D5C; }
+
+/* ── Headings ──────────────────────────────────────────── */
+h1 { font-size: 2rem; font-weight: 600; margin-bottom: 1rem; }
+h2 {
+  font-size: 1.4rem; font-weight: 600;
+  margin-top: 2rem; margin-bottom: .65rem;
+  padding-bottom: .3rem;
+  border-bottom: 1px solid #DFD7CA;
+}
+h3 { font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; }
+h4 { font-size: 1rem;   font-weight: 600; margin-top: 1.2rem; }
+
+/* ── Code ──────────────────────────────────────────────── */
+pre, div.sourceCode {
+  background-color: #EEEEED;
+  border: 1px solid #DFD7CA;
+  border-radius: .375rem;
+  padding: .9rem 1.1rem;
+  font-size: .85rem;
+  overflow-x: auto;
+  margin: 1em 0;
+}
+
+code {
+  background-color: #EEEEED;
+  color: #3E3F3A;
+  border-radius: .25rem;
+  padding: .1em .35em;
+  font-size: .875em;
+}
+
+pre code, div.sourceCode code {
+  background: none;
+  padding: 0;
+  border-radius: 0;
+  font-size: inherit;
+  color: inherit;
+}
+
+div.sourceCode { padding: 0; }
+div.sourceCode pre { border: none; margin: 0; }
+
+/* ── Tables ────────────────────────────────────────────── */
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1em 0;
+  font-size: .9rem;
+}
+
+thead th {
+  background-color: #DFD7CA;
+  color: #3E3F3A;
+  font-weight: 600;
+  padding: .5rem .75rem;
+  border-bottom: 2px solid #c8c0b4;
+  text-align: left;
+}
+
+td, th { padding: .4rem .75rem; border-bottom: 1px solid #e8e2d8; }
+tbody tr:hover { background-color: rgba(223,215,202,.2); }
+
+/* ── TOC sidebar ───────────────────────────────────────── */
+aside#toc, aside .toc, aside nav.toc { font-size: .875rem; }
+
+aside h2.h6 {
+  text-transform: uppercase;
+  font-size: .68rem;
+  letter-spacing: .07em;
+  color: #6c757d;
+  font-weight: 600;
+  margin-bottom: .5rem;
+  border: none;
+  padding: 0;
+}
+
+aside .toc, aside #TOC {
+  position: sticky;
+  top: 5rem;
+  max-height: calc(100vh - 6rem);
+  overflow-y: auto;
+}
+
+aside ul {
+  list-style: none;
+  padding-left: .9rem;
+  margin: 0;
+}
+aside > nav > .toc > ul,
+aside .toc > ul { padding-left: 0; }
+
+aside li { margin: .1rem 0; }
+
+aside a {
+  color: #6c757d;
+  text-decoration: none;
+  display: block;
+  line-height: 1.55;
+}
+aside a:hover { color: #325D88; }
+
+/* ── Home page cards ───────────────────────────────────── */
+.doc-card {
+  border: 1px solid #DFD7CA;
+  border-radius: .375rem;
+  padding: 1.1rem 1.25rem;
+  height: 100%;
+  background: #fff;
+  transition: border-color .15s, box-shadow .15s;
+}
+.doc-card:hover {
+  border-color: #325D88;
+  box-shadow: 0 2px 8px rgba(50,93,136,.1);
+}
+.doc-card h5 { font-size: 1rem; font-weight: 600; margin-bottom: .4rem; }
+.doc-card p  { font-size: .875rem; color: #6c757d; margin-bottom: .6rem; }
+.doc-card a.stretched-link::after { z-index: 1; }
+
+/* ── Badges row ────────────────────────────────────────── */
+.badge-row { margin-bottom: 1rem; line-height: 2; }
+.badge-row img { margin-right: .25rem; }
+
+/* ── ── ── DARK MODE ── ── ── ──────────────────────────── */
+
+[data-bs-theme="dark"] body  { background-color: #343739; color: #DFD7CA; }
+
+[data-bs-theme="dark"] .navbar {
+  background: color-mix(in oklab, color-mix(in oklab, #343739 92%, var(--bs-primary)) 95%, #DFD7CA);
+  border-bottom-color: #495057;
+}
+
+[data-bs-theme="dark"] a       { color: #7ba8d0; }
+[data-bs-theme="dark"] a:hover { color: #a5c4e8; }
+
+[data-bs-theme="dark"] .navbar .nav-link.active { color: #7ba8d0 !important; }
+
+[data-bs-theme="dark"] h1,
+[data-bs-theme="dark"] h2,
+[data-bs-theme="dark"] h3,
+[data-bs-theme="dark"] h4 { color: #DFD7CA; }
+
+[data-bs-theme="dark"] h2 { border-color: #495057; }
+
+[data-bs-theme="dark"] pre,
+[data-bs-theme="dark"] div.sourceCode {
+  background-color: #2C2F31;
+  border-color: #495057;
+  color: #DFD7CA;
+}
+
+[data-bs-theme="dark"] code {
+  background-color: #2C2F31;
+  color: #DFD7CA;
+}
+
+[data-bs-theme="dark"] div.sourceCode span[class] { color: #DFD7CA !important; }
+
+[data-bs-theme="dark"] thead th {
+  background-color: #3d4043;
+  color: #DFD7CA;
+  border-color: #495057;
+}
+[data-bs-theme="dark"] td,
+[data-bs-theme="dark"] th  { border-color: #3d4043; }
+[data-bs-theme="dark"] tbody tr:hover { background-color: rgba(73,80,87,.3); }
+
+[data-bs-theme="dark"] aside a       { color: #8e9499; }
+[data-bs-theme="dark"] aside a:hover { color: #7ba8d0; }
+
+[data-bs-theme="dark"] .doc-card {
+  background: #2C2F31;
+  border-color: #495057;
+}
+[data-bs-theme="dark"] .doc-card:hover { border-color: #7ba8d0; }
+[data-bs-theme="dark"] .doc-card p     { color: #8e9499; }

package/docs-src/md-to-html.lua

@@ -1,6 +1,6 @@
--- Rewrite .md links to .html in pandoc output
-function Link(el)
-  el.target = el.target:gsub("%.md$", ".html")
-  el.target = el.target:gsub("%.md#", ".html#")
-  return el
-end
+-- Rewrite .md links to .html in pandoc output
+function Link(el)
+  el.target = el.target:gsub("%.md$", ".html")
+  el.target = el.target:gsub("%.md#", ".html#")
+  return el
+end