Fix peewee model attributes missing from generated docs (#86)#116
Merged
Conversation
The `skip_inherited_members` autodoc-skip-member callback assumed the hook receives the class as `obj`, but Sphinx passes the member itself. The check `name not in obj.__dict__` was therefore true for nearly every member, so the callback skipped almost all class members site-wide -- e.g. EvalRunner documented 1 member instead of 8. peewee models made it most visible since all their content is field attributes. - Replace the callback with `skip_peewee_internals`, which surfaces real fields/methods and only filters genuine peewee-metaclass noise (the per-model `DoesNotExist` exception and the `<fk>_id` aliases that duplicate each foreign key). Inherited members stay excluded via the existing `inherited-members: False`. - Add `numpydoc_show_class_members = False` to drop numpydoc's redundant per-class summary tables, which listed every inherited peewee.Model method as noise and triggered "stub file not found" warnings. - Expand the DEVELOPMENT.md docs-building section (deps, output location, autobuild server, the docclean caching gotcha, the peewee/autodoc note). Verified by clean rebuild: Metric documents all 21 fields, EvalRunner all 8 methods, no DoesNotExist/FK-alias/inherited-method noise, warnings down 35->27. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a `docs` job to validate.yaml that runs `uv sync --group docs && make html` on every push, so doc-build breakage is caught on PRs instead of only when the deploy-to-main github-pages workflow runs. Enable uv's built-in dependency cache (`enable-cache: true`) in both workflows. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
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.
Fixes #86.
Root cause
The
skip_inherited_membersautodoc-skip-member callback indocs/conf.pywas written assuming the hook receives the class asobjand checksname in cls.__dict__. Sphinx actually passes the member itself asobj, soname not in obj.__dict__was true for essentially every member and the callback skipped it.This was broader than the reported symptom: it silently suppressed nearly every class member site-wide, not just peewee fields.
EvalRunner, for instance, documented only 1 member instead of its 8 methods. The peewee models just made it most visible since all their content is field attributes.Changes
skip_peewee_internals, which surfaces all real fields/methods and only filters genuine peewee-metaclass noise: the per-modelDoesNotExistexception and the<fk>_idaliases that duplicate each foreign key (detected vianame != field.name, since the alias shares the FK'sFieldobject). Real*_idfields liketool_call_idare kept. Inherited members stay excluded via the existinginherited-members: False.numpydoc_show_class_members = Falseto drop numpydoc's per-class summary tables. These duplicated autodoc's member docs and listed ~45 inheritedpeewee.Modelmethods (save,select,bulk_create…) as noise on every model page (pre-existing). It also eliminates the "stub file not found" warnings those tables':toctree:would emit.DEVELOPMENT.mddocs-building section: installing thedocsdependency group, output location, thesphinx-autobuildserver, themake doccleancaching gotcha (essential for config changes to take effect), scanning warnings, and a note on the peewee/autodoc interaction.Verification
Clean rebuild (
make docclean html):Metricdocuments all 21 fields;EvalRunnerall 8 methodsDoesNotExist/ FK-alias / inherited-method noise🤖 Generated with Claude Code