mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
boshu
91 lines
2.7 KiB
Python
91 lines
2.7 KiB
Python
"""Generate CLI reference pages at MkDocs build time.
|
|
|
|
Copies the canonical generated CLI docs from cli/docs/ into docs/cli/ so they
|
|
render inside the published site without requiring a symlink (which the repo
|
|
bans). Source of truth remains cli/docs/COMMANDS.md, regenerated by
|
|
scripts/generate-cli-reference.sh.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import mkdocs_gen_files
|
|
|
|
REPO_ROOT = Path(__file__).resolve().parent.parent.parent
|
|
CLI_DOCS = REPO_ROOT / "cli" / "docs"
|
|
|
|
|
|
def emit(src: Path, dest: str, title: str) -> None:
|
|
if not src.is_file():
|
|
# Fail the build rather than silently publishing a "file-not-found"
|
|
# page. CLI reference drift would otherwise ship unnoticed.
|
|
raise SystemExit(
|
|
f"[gen_cli_reference] FATAL: missing source {src.relative_to(REPO_ROOT)}. "
|
|
f"Run scripts/generate-cli-reference.sh to regenerate {title}, "
|
|
f"or remove the docs/_hooks/gen_cli_reference.py emit() call if the "
|
|
f"reference is intentionally retired."
|
|
)
|
|
|
|
content = src.read_text(encoding="utf-8")
|
|
# Prepend a short header note that this page is auto-generated.
|
|
header = (
|
|
f"<!-- Auto-generated from {src.relative_to(REPO_ROOT)} at build time. "
|
|
f"Edit the source, not this file. Regenerate with "
|
|
f"`scripts/generate-cli-reference.sh`. -->\n\n"
|
|
)
|
|
with mkdocs_gen_files.open(dest, "w") as fh:
|
|
fh.write(header + content)
|
|
|
|
|
|
def emit_index() -> None:
|
|
body = """# CLI Overview
|
|
|
|
The `ao` CLI provides deterministic repository checks and optional evidence
|
|
utilities. Semantic workflows remain skills rather than CLI lifecycle commands.
|
|
|
|
<div class="grid cards" markdown>
|
|
|
|
- :material-console: **[Command Reference](commands.md)**
|
|
Every `ao` command with flags, examples, and exit codes. Auto-generated from
|
|
`ao --help`.
|
|
|
|
- :material-map: **[CLI Surface](../cli-surface.md)**
|
|
Generated public command inventory and coverage classification.
|
|
|
|
</div>
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Official install script
|
|
bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
|
|
```
|
|
|
|
This installs:
|
|
|
|
- The `ao` binary to `~/.local/bin/ao`
|
|
- Skills to `~/.claude/skills/`
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
ao --version # Verify install
|
|
ao rpi phased "fix the flaky auth test" # Full Research -> Plan -> Implement -> Validate cycle
|
|
ao status # Where was I?
|
|
ao goals measure # Fitness gate
|
|
```
|
|
"""
|
|
with mkdocs_gen_files.open("cli/index.md", "w") as fh:
|
|
fh.write(body)
|
|
|
|
|
|
def main() -> None:
|
|
emit_index()
|
|
emit(CLI_DOCS / "COMMANDS.md", "cli/commands.md", "Command Reference")
|
|
print("[gen_cli_reference] emitted cli/{index,commands}.md", file=sys.stderr)
|
|
|
|
|
|
main()
|