Adds tools/api_audit.py, a read-only static audit of the public API surface,
and docs/api-audit.md, its first run against this revision.
The audit answers three questions the reference cannot answer about itself:
1. Does every declared export exist, have a docstring, and appear in
docs/api.md? It reads the root __all__ plus each submodule's __all__.
2. How complete is each public definition? Docstring presence, detected
docstring convention, parameter and return annotations.
3. Which public names do examples and tests actually use but the reference
never explains? That set is the real documentation gap.
It parses with ast and never imports the package, so it costs no numpy/cv2
import and cannot be affected by the environment.
Findings on this revision (full detail in docs/api-audit.md):
- 393 public classes/methods/functions; 65% have a docstring, 32% have a fully
annotated signature, 38 document their return value.
- 243 docstrings are unstructured prose, 137 are absent, 13 use Google or NumPy
sections. There is effectively one convention: none.
- 9 of the 18 root exports are absent from docs/api.md, including
StreamPipeline, StreamRecorder, mosaic_videos and FFCFrameProcessor - the
pipelined multi-stream and offline-recording paths.
- Six sub-surfaces have zero coverage in the reference: unroll (18 exports),
capture (17), hhd + solvers (7), pipeline (3), export (2).
- 74 names are used by examples or tests but absent from the reference.
- 21 public classes are exported nowhere; LowpassFilter is documented in
docs/api.md and importable, but declared in no __all__.
No behaviour change: a new tool and a new document, no source file touched.
`tools/lint_gate.py` now also runs `D:\orisys_ws\scripts\doc_lint.py`, the
workspace's single documentation gate, alongside Ruff:
- changed Markdown by default, the whole corpus under --all
- `--files` names Python files explicitly, so it skips the doc gate
- `--no-docs` opts out
- the docs verdict is reported even when Ruff is missing, so a missing
linter cannot hide it (the exit code still signals the environment problem)
The doc rules live in exactly one place on purpose: this file is duplicated
across three repositories and had already drifted, so adding a fourth copy of
lint logic would repeat the mistake. Failing checks are the documentation
budget, inventory membership, a declared kind, unresolved mojibake, paragraph
walls, and duplicate explanations across documents. Emphasis density is
advisory only - measured as a continuum from 12% to 48% across the corpus, so
no threshold separates signal from noise.
Pre-existing oversized documents are recorded as budget-exempt with a written
reason in D:\orisys_ws\docs\inventory.json, and pre-existing findings are
baselined there, so this gate is red only for new regression.
With Ruff unavailable in the current environment the doc half still reports,
which is how it was verified.
ykcheungab
zhangyijian