Erich Blume
5c79a8dbe2
## Summary - Add `doc-random` mise task that selects a random documentation card for review - Add how-to/knowledgebase section with review-documentation guide - Add Caddy reference card with proxy configuration details - Fix replication tutorial sequence (tailscale-setup now links to core-services) - Fix "BluemeOps" typo in tailscale-setup - Clean up obsolete zk/ directory references from doc-links ## Deployment and Testing - [x] `mise run doc-random` works and displays a random card - [x] `mise run doc-links` passes (all wiki-links valid) - [x] Pre-commit hooks pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/98
88 lines
2.6 KiB
Text
Executable file
88 lines
2.6 KiB
Text
Executable file
#!/usr/bin/env -S uv run --script
|
|
# /// script
|
|
# requires-python = ">=3.12"
|
|
# dependencies = ["rich>=13.0.0"]
|
|
# ///
|
|
#MISE description="Select a random documentation card for review"
|
|
"""Select a random documentation card for review.
|
|
|
|
This script scans all markdown files in the docs/ directory (excluding
|
|
changelog.d/), selects one at random, and displays it for review.
|
|
|
|
Useful for periodic knowledge base maintenance and verification.
|
|
|
|
Usage: mise run doc-random
|
|
"""
|
|
|
|
import random
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from rich.console import Console
|
|
from rich.markdown import Markdown
|
|
from rich.panel import Panel
|
|
|
|
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
|
|
|
|
|
def get_all_docs() -> list[Path]:
|
|
"""Get all documentation markdown files, excluding changelog.d."""
|
|
docs = []
|
|
for md_file in DOCS_DIR.rglob("*.md"):
|
|
# Skip changelog fragments
|
|
if "changelog.d" in md_file.parts:
|
|
continue
|
|
docs.append(md_file)
|
|
return docs
|
|
|
|
|
|
def main() -> int:
|
|
console = Console()
|
|
|
|
docs = get_all_docs()
|
|
if not docs:
|
|
console.print("[bold red]No documentation files found![/bold red]")
|
|
return 1
|
|
|
|
# Select a random document
|
|
selected = random.choice(docs)
|
|
rel_path = selected.relative_to(DOCS_DIR)
|
|
|
|
# Display header
|
|
console.print()
|
|
console.print(Panel(
|
|
f"[bold cyan]{rel_path}[/bold cyan]\n"
|
|
f"[dim]{len(docs)} total docs in knowledge base[/dim]",
|
|
title="[bold]Random Documentation Card[/bold]",
|
|
border_style="cyan",
|
|
))
|
|
console.print()
|
|
|
|
# Display the file content
|
|
content = selected.read_text()
|
|
console.print(Markdown(content))
|
|
|
|
# Review checklist
|
|
console.print()
|
|
console.print(Panel(
|
|
"[bold]Review Checklist:[/bold]\n\n"
|
|
"• Is the information accurate and up-to-date?\n"
|
|
"• Are there broken or missing wiki-links?\n"
|
|
"• Should this card link to other related cards?\n"
|
|
"• Is the card too large and should be split?\n"
|
|
"• Is the card too small and should be merged?\n"
|
|
"• Does the frontmatter (tags, title) make sense?\n"
|
|
"• Is the card in the correct category (reference/how-to/etc)?\n\n"
|
|
"[bold]Verify Deployed State:[/bold]\n\n"
|
|
"• If ArgoCD app: is it synced? (argocd app get <app>)\n"
|
|
"• If Ansible role: does it apply idempotently? (--check --diff)\n"
|
|
"• If Pulumi: is there drift? (pulumi preview)",
|
|
title="[bold yellow]Review Guidance[/bold yellow]",
|
|
border_style="yellow",
|
|
))
|
|
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|