cli.py

F_index(ctx: Context, full: bool) -> None

Refresh the graph before anything reads it. Default is incremental-when-a- graph-exists: re-parse only what changed since the last build (fast on big repos, the whole point). --full forces a from-scratch rebuild; a first index (no db yet) is always full regardless. index() decides the safe path. A spinner covers the wait (this is the one silent-slow step), then one line says what it did.

F_snapshot(ctx: Context) -> dict[str, float]

{tracked file: mtime} — everything that can change the generated docs.

Tracked files only (git ls-files), matching what the indexer sees, minus the docs and site trees: regeneration writes there, so watching them would retrigger forever. A vanished file drops out of the dict, which is itself a change.

F_watch(ctx: Context, html: bool) -> int

documate --watch — poll for source changes, regenerate on each one.

A dumb 1s mtime poll, no watcher dependency: an idle cycle is one git ls-files + stats, and a regeneration is incremental, so the loop stays sub-second even on large repos. A brand-new file starts triggering once it's git-tracked (git add) — untracked files are invisible to the poll and the indexer alike. Ctrl-C stops.

Each cycle prints which source files triggered it, then a colored unified diff of every doc page that changed in response — the live terminal view of the docs.

F_repo_here() -> bool

Is the cwd inside a git work tree? Decides whether a bare documate can act (there's a repo to document) or should explain itself (the help screen).

Fbuild_parser() -> argparse.ArgumentParser

Build the one flat parser: no subcommands, so documate -h is the whole surface on one screen (rendered through rich-argparse, the one cosmetic dependency). The three modes come first, overrides after.

F_scaffold(ctx: Context) -> None

--init: write the starter config, then teach the ignore defaults so the user knows what's already skipped before they add to it. Never clobbers an existing config — that path just says the file is already there. Behaviourally a no-op on this run (the scaffold is defaults only), so the docs + gate that follow see exactly what they would have without it.

F_dispatch(args) -> int

Route one parsed invocation: index first (every mode reads the graph), then the mode — gate only (--check), the model layer (--ai), or the default job: docs, site if asked, then either the watch loop or the gate. --watch skips the gate on purpose: it's a dev loop, and gating every save would be noise.

Fmain(argv=None) -> int

Console entry point: parse argv, dispatch, return the exit code.

Bare documate inside a repo does the whole job; outside any repo (nothing to act on) it lands on the help screen instead of an error. -h/--help and argparse errors are converted from SystemExit to plain return codes so embedders (and the tests) get a value, not an exit.