ci: gate doc quality in CI and pre-commit to prevent future degradation

[planetf1]

Context

The audit_coverage.py --quality tool detects missing/incomplete docstrings across the public API. The --fail-on-quality flag (added in PR #611) causes the tool to exit 1 when quality issues are found, making it usable as a hard gate in CI or pre-commit.

The goal is to prevent future degradation once the baseline is clean.

Pre-requisites (must land first)

These open items need to complete before this gate makes sense to enable:

• PR docs: Docs/api pipeline improvements #611 — docs pipeline tooling including --fail-on-quality flag (this is the enabler)
• PR docs: improve docstrings for API reference (#612) #614 / Issue docs: improve module-level docstrings for API reference #612 — module-level docstring improvements
• Issue docs: add Args/Returns sections to public function docstrings #613 — Args/Returns sections for public functions
• Issue fix: add missing type annotations to public API functions #615 — missing type annotations on public API (surfaces additional no_returns/no_args once fixed)

The gate should only be enabled once the audit reports 0 quality issues, so it starts green.

Work required

1. Extend docs-autogen-pr.yml — add a quality audit step using --quality --fail-on-quality after doc generation on tag-triggered doc PRs.

2. Consider a pre-commit hook — a local hook calling audit_coverage.py --quality --fail-on-quality would catch regressions at commit time. Note Griffe loads the full package (~10 s), so CI may be more practical than pre-commit for most contributors.

Goal

Once in place, any PR that removes a docstring, strips an Args:/Returns: section, or adds an undocumented public symbol will fail the build automatically.

[planetf1]

We should also consider the overlap/alignment with existing ruff etc checks. From first glance they are broadly compatible.

[planetf1]

Coverage metric enhancement — include methods

Currently the coverage metric counts only top-level classes and module-level functions (365 symbols, 99.45% documented). Methods are excluded because coverage is measured by existence of a dedicated MDX file, and methods don't get their own pages — they're documented as sections within the class page.

To make coverage truly representative of the full public API, a future enhancement could:

• Parse class MDX pages to verify each public method is present as a documented section, or
• Restructure docs generation to give each method its own MDX file

For now, method-level completeness is captured by the --quality audit (soft-fail in CI). The hard gate added by this issue should cover method docstrings too (i.e., no --no-methods) once the issue count reaches 0.

[planetf1]

Interatively fixing up the underlying issues in prep for enabling this.