Migrate in-code docs to Google docstyle, document the public API, and gate CI on both

[kozlov721]

Purpose

Our in-code documentation is mid-migration to Google docstyle. luxonis-ml has
moved; modelconverter was still on Epytext, and its CLI commands used a third
style (numpydoc) on top of that. This brings modelconverter in line with
luxonis-ml's 3460597 ("Enhance documentation"), documents the public API,
and puts both under CI so neither can regress.

The docs also could not be built: pydoctor emitted 14 warnings, so a
warnings-as-errors build was impossible.

Specification

Docstyle migration. docformatter style epytext → google, ruff's D
rules enabled with the same ignore list luxonis-ml uses. Every Epytext
docstring converted (@type/@param/@rtype/@return/@raises →
Args:/Returns:/Yields:/Raises:; C{}/L{} → literals/references). The
cyclopts CLI commands' numpydoc Parameters blocks are converted too — these
render into modelconverter --help.

Warning-free docs build. pydoctor --docformat=google -W now exits 0. Two
causes: single backticks are cross-references in Google/RST mode, so
unresolvable names had to become literals; and pydoctor ast.parses every
string literal inside an annotation, so Parameter(help="some help") and
Field(alias="from") failed to parse. launcher's six option descriptions
moved from Parameter(help=...) into its (previously absent) docstring, which
cyclopts reads identically; EncodingConfig.from_ now uses a plain Field()
default. Those 7 warnings predate this PR.

Public API documented and enforced. Every public module, package, class,
method and function now has a docstring, and D100–D107 are enforced.
tests/* is exempt from D103 alone — a docstring on each of the 410
def test_* would be noise, while the module, class and helper docstrings
around them are not.

Input formats corrected. The converter takes ONNX, OpenVINO IR and TFLite,
and the accepted set is per-target: the CLI rejects an IR for anything but
RVC2/RVC3, TFLite reaches RVC4/Hailo via snpe-tflite-to-dlc and
translate_tf_model, and RVC2/RVC3 via an ONNX conversion their exporter logs
as experimental. Each sub-package states what it accepts; the top-level defers
to them. .pt/.pth are not documented, being no longer relevant.

CI. A pre-commit job (running prek, as luxonis-train and
luxonis-ml's dev/uv branch do) and a docs job (pydoctor -W) gate every
test job: pre-commit → docs → unit → integration → coverage.

Dependencies & Potential Impact

No runtime dependency changes. requirements-dev.txt swaps pre-commit~=4.6
for prek~=0.4.13; .pre-commit-config.yaml is unchanged, as prek reads it
as-is. CI gains a pydoctor~=25.10 install in the docs job (no project deps
needed — pydoctor reads sources rather than importing them).

No behaviour change. Every docstring commit is AST-proven docstring-only
against its parent: no signature, logic, import or behaviour changes. Two
deliberate exceptions, both called out in their commit messages:

• EncodingConfig.from_ declares its alias via a plain Field() default
  instead of Annotated[..., Field(...)]. Identical pydantic semantics —
  alias parsing, serialization alias and default all verified unchanged.
• One line of rvc4/analyze.py: a return inside a try moved into an else
  block. That TRY300 has been failing on main; documenting the file brought
  it under the hook and blocked the commit. All three paths are unchanged.

Reviewers should note that ruff derives publicness from __all__, so
D101/D102 never fired for Layout, QuantizationMode, InputFileType and
InputFileType.from_path in utils.types. They are documented here, but the
newly enabled rules will not catch the next such symbol.

Testing & Validation

• pydoctor --docformat=google -W exits 0 (verified in a venv containing only
  pydoctor, i.e. exactly what the CI job does), and verified to exit non-zero
  on a deliberately broken reference.
• ruff check . — all checks passed, no exclusions. ruff format --check . —
  116 files clean.
• prek run --all-files — 16 hooks pass; verified to exit 1 on a bad file.
• 827 unit tests pass, 1 pre-existing skip.
• modelconverter --help diffed before/after for all seven commands: every
  parameter still renders; the only changes are imperative summaries, a fron
  typo fix, and quoted literals now rendering as code.
• The ~300 new docstrings were written by a multi-agent pass and then
  adversarially verified against the implementation, which corrected 52 factual
  errors — including EncodingConfig's from_/to documented backwards, a
  Raises: that cannot fire, and an undocumented in-place mutation of the
  caller's config.
• Conversion tests (tests/conversion) were not run — they need the per-backend
  Docker images and, for some, an attached device.

Deployment Plan

None / not applicable — documentation, lint configuration and CI only. No
release or rollout step; reverting the branch fully restores the previous state.

AI Usage

Assisted-by: Claude Code:claude-opus-5 ruff pydoctor prek pytest

Submitted code was reviewed by a human: NO

The author is taking the responsibility for the contribution: YES/NO

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.98%. Comparing base (459e03a) to head (cf06263).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@                      Coverage Diff                      @@
##           chore/type-gate-and-coverage     #274   +/-   ##
=============================================================
  Coverage                         99.98%   99.98%           
=============================================================
  Files                                86       87    +1     
  Lines                              7152     7176   +24     
=============================================================
+ Hits                               7151     7175   +24     
  Misses                                1        1           

Flag	Coverage Δ
conversion	43.28% <7.14%> (-0.21%)	⬇️
unit	81.71% <96.42%> (+1.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.