fix(docs): skip removed-type modules during API documentation builds

[bokelley]

The SDK 9 API docs build aborts when pdoc3 imports the intentional removed FormatCategory module. Configure a parent-package exclusion inside the documentation process so pdoc skips that module before importing it and continues documenting the supported API. Adopters retain the existing migration error when importing the removed module.

pdoc3 0.11.6 does not support the proposed !module CLI syntax. Its parent-package __pdoc__ blacklist is checked before recursive imports, so the exclusion is confined to the docs workflow and preserves any existing documentation configuration.

Validation: full API docs generation passed on Python 3.12 and a clean Python 3.11 environment with only [docs] dependencies (1,449 HTML pages; supported root/client/types/enums/FormatId pages present, removed module absent); existing migration-error regression passed; actionlint 1.7.7; make lint; make typecheck-all including mypy and pyright; make test with six workers (15,494 passed, 2,467 skipped, one expected failure, 89.86% coverage).

Fixes #1423.

[aao-secretariat]

Ladon verdict: Approve

Approve — single-file CI workflow fix, no blocking or medium findings.

What I checked:

• Only .github/workflows/docs.yml changed (+12/-1).
• The fix replaces the bare pdoc --html ... adcp call with a heredoc that sets adcp.__pdoc__["types.domains.enums.format_category"] = False before pdoc recurses, so the docs build skips the removed-type tombstone (format_category.py, which raises ImportError) instead of crashing. Mechanism is sound: pdoc3 propagates supermodule __pdoc__ keys to submodules and consults the blacklist before import_module, and this is the only module-level import-raising tombstone in domains/, so one exclusion suffices (matches scripts/post_generate_fixes.py:2727).
• No public-API/wire-shape surface touched, no generated code edited, no CI gate disabled, no credential handling, no semver-relevant change. None of the repo-specific hard gates apply.

Gate checks: gated_paths: false; no no-auto-approve team match; high_risk: false; no prior decision. Although review_decision is REVIEW_REQUIRED, row 2 only fires when gated_paths is true, which it is not here.

With no critical/high/medium findings and no escalation trigger, this falls through to row 9 → approve.

Non-blocking nit: the exclusion list is hand-coupled to the tombstone set; a future ImportError tombstone would re-break the docs build (loudly in CI, not silently). A comment pointer at the exclusion site would help future maintainers.

[bokelley]

The maintenance pointer requested in the nit is already present at docs.yml:45: “Keep in sync with the tombstones restored by scripts/post_generate_fixes.py.”

The full docs build passed with 1,449 pages, the supported FormatId page remains present, and the existing regression verifies the removed module still raises its migration error. No source change is needed for this nit.

[bokelley]

Thanks for pointing that out — the "Keep in sync with the tombstones..." comment at docs.yml:45 addresses the nit. No change needed here.

---

Generated by Claude Code