Docs sweep: fix docstring rendering, coverage gaps, AI-agents README - #20
Merged
Merged
Conversation
…t blocks) epythet repair_package fixes for DR003/DR006/DR008/DR011/DR016 rendering artifacts: missing blank lines before doctest blocks, a Markdown fence converted to RST, and __init__ docstrings for SyncStore/FileStore/JsonStore.
- base.py, util.py: indent Google-style section headers (Args/Example) so napoleon renders them as fields instead of prose (DR002); fix an unbalanced ``Mapping``s backtick span (DR010); turn bullet lists that were glued to their intro line into proper RST lists (DR008); split a block of "**kind**: ..." lines into a real bullet list to remove a stray "Unexpected indentation" Sphinx build error. - Add missing docstrings (D102/D103/D107) on previously undocumented public callables and __init__ methods, verified against the class docstrings and tests they already had. - base.py user_gettable: convert its :param:/:return: fields to Google style so pydoclint can match them against the signature (fixes a DOC101/DOC103 false "missing argument" finding). - util.py is_repl: the docstring documented a nonexistent `repl_conditions` parameter; is_repl takes no arguments -- the set it checks is the module-level `is_repl.repl_conditions` attribute. Rewrote the docstring to describe that correctly (fixes DOC102/DOC103). - README.md: add the "For AI agents" section (epythet ai-readme-check). epythet validate -i tests/ scrap/ examples/ -- config2py --level 2: before 17 Level-0.5 errors, 5 undocumented objects; after 0 errors at levels 0.5 and 1 (Sphinx build), 0 undocumented objects. pytest --doctest-modules: 127 -> 129 passed (2 new doctests added), all green.
- is_repl: the docstring said to "reassign" is_repl.repl_conditions to change the checks; the function reads the original module-level set object, so rebinding the attribute has no effect -- only mutating the set does. Corrected. - persist_after_operation / ConfigStore: dropped the "write to disk" claim; persist() only touches disk when target_kind == 'filepath', and returns serialized data without writing for 'string'/'bytes'/'dict' targets. - ConfigReader.persist: removed the invented "has nothing to persist" rationale -- it's disabled, not vacuous.
This was referenced Sep 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
WP6 documentation sweep of config2py (epythet-repair-migrate procedure, per i2mint/epythet#16).
Before / after
epythet validate -i tests/ scrap/ examples/ -- config2py --level 2Doctests (
pytest --doctest-modules config2py): 127 passed -> 129 passed, 2 skipped, all green. Full test suite (pytest): 95 passed, 1 skipped throughout, unchanged.What was fixed
epythet.repair_packageand by hand: missing blank lines before doctest blocks (DR003), a Markdown fence collapsed to inline code (DR006), bullet lists glued to their intro paragraph (DR008), a Google-styleArgs:/Example:header left unindented so it rendered as prose (DR002), an unbalanced``Mapping``sbacktick span (DR010), and a "kind: ..." block that produced a docutils "Unexpected indentation" build error.__init__methods (is_not_none_nor_empty,is_not_empty,persist_after_operation,ConfigStore.__init__,to_dict,ConfigReader.persist/__setitem__/__delitem__,SyncStore/FileStore/JsonStore.__init__,EnvironmentVariables.__init__/__repr__,AppData.__init__), each verified against the implementation.user_gettable: converted its Sphinx:param:fields to GoogleArgs:style (no wording change) so pydoclint stops reporting a false "missing argument" finding (DOC101/DOC103).is_repl: the docstring documented a nonexistentrepl_conditionsparameter and, in an earlier draft, wrongly said to "reassign"is_repl.repl_conditionsto change its checks — the function reads the module-level set object by reference, so only mutating the set works, not rebinding the attribute. Fixed both.persist_after_operation/ConfigReader.persist: an earlier draft claimedpersist()"writes to disk" unconditionally and thatConfigReader"has nothing to persist" — neither is true (persist()only writes to disk fortarget_kind == 'filepath', andConfigReader.persistis disabled, not vacuous). Both caught and fixed by an independent adversarial review pass and corrected before landing.epythet ai-readme-check .now passes).Deliberately left as-is
docsrc/was already gitignored and not committed (this repo is a v2 pilot) — nothing to remove.i2mint/epythet/actions/publish-github-pages@masterjob; no legacyepythet make . githubstep or trackeddocs/build output exists.[tool.epythet]theme override —epythet quickstart .builds clean with the auto theme; no evidence it picks wrong.warning/infofindings (D105 dunder docstrings, D212/D415/D205 napoleon formatting nits, DR011 single-backtick-as-italics on 4 pre-existing spans) are pre-existing style nits across the whole file, not coverage/correctness gaps; left alone per "entry points first, no filler."Claims declined
None — every docstring claim added or changed here was verified against the implementation or its tests (including the two follow-up corrections from the adversarial review).
https://claude.ai/code/session_01FRpcZoGP1pjBw8upjSYUD7