docs: WP6 epythet documentation sweep - #96
Merged
Merged
Conversation
…tput docsrc/ was the epythet 0.1 scaffold (template conf.py, index.rst, module_docs/, Makefile) plus two pages that automodule a non-existent mockmodule; epythet 0.2 regenerates the scaffold on every build, so it is now gitignored. The one hand-written page (the zip files how-to) moves to misc/docs/. docs/ was a 2021 HTML build that Pages does not serve (Pages serves the gh-pages branch).
…efore doctests and lists, Markdown fences to code blocks, one-line Returns to sections)
Blank lines before Google sections, code in double backticks where it carried asterisks, literal blocks for indented code lines, a dangling RST reference, and empty Returns sections filled from the code.
Drops the `epythet make . github` step from Publish (which rewrote a tracked docs/ dir the CI never actually served) and adds a github-pages job using i2mint/epythet/actions/publish-github-pages@master, matching the pattern already rolled out to other swept repos. Also adds the README "For AI agents" section via `epythet ai-readme-check --write`, pointing at llms.txt / py2store.md / objects.inv. See i2mint/epythet#16 WP6.
- PathFormat._prefix is the directory containing the part before the
first '{', not that part itself (differs when the template has no
separator right before '{', e.g. '/data/pre_{}.csv').
- LocalTextStore's path template restricts what is listed, not what
can be read/written (contradicted the class's own doctest two lines
below).
- ipython_display_val_trans dispatches HTML detection by key extension
only when key is a string longer than 4 chars, else by content sniff
-- not an unconditional "or".
20 tasks
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.
[session-link-guard] stripped Claude-Session link(s) from the PR body -- this repo is public (or its visibility could not be confirmed)
Summary
WP6 documentation sweep of
py2store(i2mint/epythet#16), continuing a previously-started branch that was reviewed line-by-line against the docstring policy and the knownepythet repairdefect classes (i2mint/epythet#27) before landing.docsrc/template (stale, referenced a non-existentmockmodule) and the tracked 2021docs/build output;docsrc/is gitignored, the one hand-written page moved tomisc/docs/.Returns:→ sections).py2store/__init__.py,access.py,persisters/local_files.py,stores/local_store.py,my/grabbers.py,key_mappers/str_utils.py,key_mappers/tuples.py) — every added example was executed and its real output pasted in.epythet make . githubCI step (which rewrote the trackeddocs/dir the CI never actually served) with the standardi2mint/epythet/actions/publish-github-pagesjob.epythet ai-readme-check --write.PathFormat._prefix,LocalTextStore's template restricting reads,ipython_display_val_trans's HTML detection order) — fixed in a follow-up commit.Before / after
epythet validatelevel 0.5 errorsepythet validatefindingspytest --doctest-modulespytestDeliberately left: 73 objects still undocumented (
epythet validateDQ001), mostly inutils/glom.py(a vendored/adapted third-party module),utils/mg_selectors.py,utils/cumul_aggreg_write.pyand optionalext/*modules — none are top-level package entry points, and the docstring policy says incorrect docs are worse than missing ones, so these were left alone rather than filled in without verifying their (often non-obvious) behaviour.Test plan
pytest(8 passed)pytest --doctest-modules py2store(74 passed, 1 skipped)epythet validate -i tests/ scrap/ examples/ --level 2 -- py2store(0 error)epythet make . html(Sphinx build succeeds)epythet ai-readme-check .(ok)