Auto-generated per-script Markdown documentation extracted from inline Python docstrings.
Each .md file in this directory documents one script from scripts/. The content is
extracted from the module-level docstring in each script file — Purpose, Inputs, Outputs,
Usage examples, and Exit Codes.
These files are committed to the repository so that documentation is readable without running any toolchain (Local Compute-First — MANIFESTO.md §3).
Tool: pydoc-markdown (via a thin wrapper script — see below) for docstring extraction,
producing plain Markdown output. No HTML build required.
Why pydoc-markdown over alternatives:
- Produces plain
.mdoutput natively — no HTML pipeline needed - Supports per-module output (one
.mdper script) - Lightweight — no Sphinx dependency tree
- Compatible with the existing module-level docstring format used across all scripts
See docs/research/scripts-documentation-generation.md for the full tool evaluation.
To regenerate documentation for all scripts:
uv run python scripts/generate_script_docs.pyTo check which docs are stale (docstring changed since last generation):
uv run python scripts/generate_script_docs.py --checkTo regenerate a single script's doc:
uv run python scripts/generate_script_docs.py --script prune_scratchpadNote:
scripts/generate_script_docs.pyis the forthcoming implementation script (see R1 indocs/research/scripts-documentation-generation.md). The initial docs in this directory were generated manually to prove the pipeline works.
| Script | Doc file | Status |
|---|---|---|
prune_scratchpad.py |
prune_scratchpad.md |
✅ Generated |
| All other scripts | — | Pending generate_script_docs.py |
- Each doc file is named
<script-name>.md(without the.pyextension) - The first line of each doc is a level-1 heading with the script name
- Sections follow the docstring structure: Purpose, Inputs, Outputs, Usage, Exit Codes
- A hidden HTML comment at the top stores the docstring content hash for staleness detection:
<!-- docstring-hash: <sha256[:8]> -->