Erich Blume
124ffb60d7
- New mise task selects a random doc card for periodic review - Add how-to/knowledgebase section with review-documentation guide - Clean up obsolete zk/ directory references from doc-links Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
84 lines
2.3 KiB
Text
Executable file
84 lines
2.3 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)?",
|
|
title="[bold yellow]Review Guidance[/bold yellow]",
|
|
border_style="yellow",
|
|
))
|
|
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|