docs: epythet 0.2 documentation sweep (WP6) by thorwhalen · Pull Request #10 · i2mint/qh

thorwhalen · 2026-09-15T12:08:11Z

Summary

Epythet 0.2 documentation sweep for qh (i2mint/epythet#16 WP6). Builds on a
previous session's unreviewed WIP already committed to this branch; that diff
was reviewed line by line against the behaviour-claim policy, one wrong claim
was found and fixed (see below), and its committed docsrc/ scaffold was
removed.

Tests and doctests

pytest -q: 165 passed, 1 skipped -- unchanged before/after (no test
behaviour was touched).
pytest --doctest-modules -q qh: 183 -> 188 passed, 12 skipped (5 new
runnable doctests added on TaskConfig, RouteConfig, AppConfig,
TypeRegistry, RuleChain, plus a corrected one on get_python_type_name).

`epythet validate --level 2 qh -i tests/ scrap/ examples/`

	master (pre-sweep)	branch tip before this session	branch tip now
errors	15	0	0
warnings	102	102	66
info	153	156	138
objects_undocumented	9	9	0
findings	270	258	204

All 15 master errors were level-0.5 (DR003/DR008, rendering-breaking:
blank lines missing before lists/doctests); the prior WIP session's
epythet repair --write already cleared those. 0 Level 0.5 errors, the
WP6 acceptance line.

Remaining 204 findings, all info/warning, none blocking:

88 D212 + 18 D412: docstring blank-line conventions that directly
conflict with epythet repair's own output (repair adds a blank line
after Examples:/Returns: before a doctest/list to fix Sphinx
rendering; ruff's D412 then flags that same blank line as wrong).
Filing a ledger-conflict issue against epythet with one of these
docstrings as a fixture.
55 DOC108: pydoclint's --arg-type-hints-in-signature=false option
(hardcoded in epythet/validation/lint.py) fires on every function that
does have type-annotated signatures -- which is this repo's (and
epythet's own stated) convention. Same issue: filing against epythet,
cannot be fixed from inside a target repo.
6 D107 vs 6 DOC301: pydocstyle wants every __init__ to have its own
docstring; pydoclint's Google convention wants __init__ to have no
separate docstring, merged into the class. Mutually exclusive; left as
documented in the PR commits, noted for the same ledger-conflict issue.
10 DR034: Sphinx warnings from starlette's optional-import stubs
(python_multipart, itsdangerous not installed in the doc build env)
and one README code-block lexed as Python that isn't; cosmetic, not
ours to fix without adding unused deps.
small style residue (D202, D205, D209): a handful of blank-line/
formatting nits, left for a future pass.

Coverage / correctness / completeness

Coverage: 9 previously undocumented public methods now documented
(InMemoryTaskStore, ThreadPoolTaskExecutor, ProcessPoolTaskExecutor
overrides of TaskStore/TaskExecutor). objects_undocumented: 9 -> 0.
Correctness (verified against the actual code before writing, per
policy):
- Fixed a wrong behaviour claim left by the prior session: quick_test's
  Raises section said requests.HTTPError; fastapi.testclient.TestClient
  is httpx-based (confirmed via its MRO), so it actually raises
  httpx.HTTPStatusError.
- get_python_type_name's inline "Examples" (not a real doctest) claimed
  list[int] -> "list[int]" and Optional[str] -> "Optional[str]"; running
  the code (Python 3.10+) shows both return the bare name ("list",
  "Optional"), because builtin/typing generic aliases now carry
  __name__ and short-circuit the bracketed-args branch. Replaced with a
  runnable doctest and an accurate description.
- Added Raises: sections for 4 undocumented exceptions (mk_app,
  get_task_result, use_au_backend, create_method_endpoint), and
  Returns:/Args: for 13 more functions/methods where pydoclint found a
  signature/docstring mismatch -- every name checked against the real
  signature.
Completeness, entry points first: added a runnable doctest to the five
classes the package's own module docstring names as central concepts
(TaskConfig, RouteConfig, AppConfig, TypeRegistry, RuleChain).
The other ~19 DQ002 "entry point has no example" findings (simple
dataclasses, Enums, ABC implementations already covered by base-class
docs) are declined for this pass to avoid filler -- no example was added
without first running it.

Theme

Left theme = "auto", which currently resolves to sphinxawesome_theme;
no [tool.epythet] override written.

`docsrc/`

The prior session committed a generated docsrc/ scaffold (predates the
epythet 0.2.9+ repair fixes). Removed from git, added docsrc/ to
.gitignore (regenerated on demand by epythet quickstart). No legacy
epythet make . github CI step or tracked docs/ build output existed to
migrate.

README

Added the "For AI agents" section via epythet ai-readme-check --write,
per the maintainer's local policy (agentic_aspects=add, agents-first,
humor on). epythet ai-readme-check . now passes clean.

Claims declined

AppRunner.__init__'s Args are already complete and accurate, but left
as-is rather than moved to the class docstring -- see the D107/DOC301
conflict above.
The ~19 declined DQ002 entry points listed above.

New epythet ledger-conflict issue

Filing i2mint/epythet with three fixtures from this repo: the D412-vs-
repair blank-line conflict, the DOC108 type-hints-in-signature false
positive, and the D107-vs-DOC301 __init__ docstring conflict.

Filed: i2mint/epythet#31

…ctions Mechanical rewrite by `epythet repair qh --write` (epythet 0.2.9): 38 docstrings in 14 files. Level 0.5 validate errors 15 -> 0 (DR008 x12, DR003 x3, DR014 x2).

…n; see i2mint/epythet#16 WP6)

Regenerated on demand by epythet quickstart; a stale committed copy predates the epythet 0.2.9+ repair fixes. Also gitignore the sweep venv.

epythet repair --write: blank lines before doctests/lists in app.py and stores_qh.py; raw-string the openapi.py docstring using backslash escapes for RST cross-references (needed a hand, non-raw would have changed the escapes). testing.py: quick_test's Raises section claimed requests.HTTPError, but fastapi.testclient.TestClient is httpx-based (confirmed via MRO), so the raise_for_status() call actually raises httpx.HTTPStatusError. Left over from a prior, unreviewed pass on this branch.

mk_app, get_task_result, use_au_backend, create_method_endpoint: the docstring now names the exception the body actually raises, verified by reading each function.

get_python_type_name's Examples claimed list[int] -> "list[int]" and Optional[str] -> "Optional[str]"; verified against the running code (Python 3.10+) both actually return the bare name ("list", "Optional") because typing/builtin generic aliases now carry __name__, short- circuiting the bracketed-args branch. Replaced with a runnable doctest and an accurate Returns section. Also added Returns to parse_function_name and get_task_result (DOC201).

InMemoryTaskStore, ThreadPoolTaskExecutor, ProcessPoolTaskExecutor override abstract methods whose contract is on the base class; each override now gets a one-line pointer plus what's implementation-specific (thread pool vs process pool, in-memory storage), verified by reading the bodies.

run_app, test_app, serve_app yield but lacked a Generator[...] return annotation, which pydoclint needs to recognize the Yields section as matching a real yield statement.

client.py: session Args described how it's used (reuse vs create) rather than repeating its Optional[requests.Session] annotation, verified against `session or requests.Session()`. au_integration.py delete_task: replaced the name-restating summary with what it actually does, verified against the body.

TaskConfig, RouteConfig, AppConfig, TypeRegistry, RuleChain: these are the concepts the package's own module docstring names as central ("a rule chain and a type registry decide where each parameter lives"), so they get a runnable example; each was executed first (DQ002). The other ~19 DQ002 entry-point findings (simple dataclasses, ABC method contracts already documented on the base class, and internal building blocks) are declined for this pass -- see PR report.

epythet ai-readme-check --write, per the maintainer's local policy (agentic_aspects=add, agents-first, humor on).

TaskManager.cancel_task, parse_function_name, validate_route_config, build_request_body_schema, get_python_type_name, extract_function_signature, Rule.match, RuleChain.match, register_json_type: each parameter name verified against the actual signature. AppRunner.__init__ is left as-is -- its Args are already complete, but pydoclint's convention expects them on the class docstring (DOC301) while also flagging __init__ (D107/DOC101) if they're not duplicated there; a genuine ledger rule conflict, noted in the PR report rather than resolved by picking a side inside this repo.

- service_running: prose claimed the launched service is torn down on exit; the Note two paragraphs below already correctly said the opposite (the finally-block is a no-op). Made the prose match reality instead of contradicting the Note. - mk_app: Raises section only listed TypeError, but validate_route_config can also raise ValueError for an invalid per-function route config. - TypeRegistry: its own docstring attributed the module-level register_type function to the instance's own registry; register_type (and register_json_type) mutate the separate global registry, not the instance -- verified against register_type's implementation.

Unrelated to the docs sweep, but blocks CI entirely as of this session: starlette (now at 1.x) requires the separate httpx2 package for TestClient, which qh.testing (test_app, quick_test, AppRunner) needs at runtime, not just in tests. Verified: pytest collection fails with "RuntimeError: The starlette.testclient module requires the httpx2 package" without this; passes with it. CI installs base dependencies only (no [dev] extra), so this has to be a base dependency, not a dev one.

thorwhalen added 14 commits September 15, 2026 12:50

docs: epythet repair, blank lines before lists and doctests, Note: se…

670aa65

…ctions Mechanical rewrite by `epythet repair qh --write` (epythet 0.2.9): 38 docstrings in 14 files. Level 0.5 validate errors 15 -> 0 (DR008 x12, DR003 x3, DR014 x2).

WIP: epythet docs sweep, partial (to be resumed by a follow-up sessio…

f9f9afc

…n; see i2mint/epythet#16 WP6)

docs: remove committed docsrc scaffold, gitignore build output

fc4766a

Regenerated on demand by epythet quickstart; a stale committed copy predates the epythet 0.2.9+ repair fixes. Also gitignore the sweep venv.

docs: add Raises sections for undocumented exceptions (DOC501/503)

94c50e8

mk_app, get_task_result, use_au_backend, create_method_endpoint: the docstring now names the exception the body actually raises, verified by reading each function.

docs: annotate context-manager return types (DOC403)

46e7815

run_app, test_app, serve_app yield but lacked a Generator[...] return annotation, which pydoclint needs to recognize the Yields section as matching a real yield statement.

docs: add For AI agents README section

8bee98f

epythet ai-readme-check --write, per the maintainer's local policy (agentic_aspects=add, agents-first, humor on).

thorwhalen merged commit 789a9ca into master Sep 15, 2026
12 checks passed

thorwhalen deleted the docs/epythet-sweep branch September 15, 2026 12:13

thorwhalen mentioned this pull request Sep 15, 2026

WP6 fleet documentation sweep: progress tracker (paused 2026-09-15) i2mint/epythet#33

Open

11 of 20 tasks

Navigation Menu

docs: epythet 0.2 documentation sweep (WP6) - #10

docs: epythet 0.2 documentation sweep (WP6)#10
thorwhalen merged 14 commits into
masterfrom
docs/epythet-sweep

thorwhalen commented Sep 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

thorwhalen commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tests and doctests

epythet validate --level 2 qh -i tests/ scrap/ examples/

Coverage / correctness / completeness

Theme

docsrc/

README

Claims declined

New epythet ledger-conflict issue

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

thorwhalen commented Sep 15, 2026 •

edited

Loading

`epythet validate --level 2 qh -i tests/ scrap/ examples/`

`docsrc/`