Skip to content

Fix peewee model attributes missing from generated docs (#86)#116

Merged
levon003 merged 2 commits into
mainfrom
docs/fix-peewee-attributes-issue-86
Jun 13, 2026
Merged

Fix peewee model attributes missing from generated docs (#86)#116
levon003 merged 2 commits into
mainfrom
docs/fix-peewee-attributes-issue-86

Conversation

@levon003

Copy link
Copy Markdown
Member

Fixes #86.

Root cause

The skip_inherited_members autodoc-skip-member callback in docs/conf.py was written assuming the hook receives the class as obj and checks name in cls.__dict__. Sphinx actually passes the member itself as obj, so name 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

  • Replace the buggy callback with skip_peewee_internals, which surfaces all 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 (detected via name != field.name, since the alias shares the FK's Field object). Real *_id fields like tool_call_id are kept. Inherited members stay excluded via the existing inherited-members: False.
  • Add numpydoc_show_class_members = False to drop numpydoc's per-class summary tables. These duplicated autodoc's member docs and listed ~45 inherited peewee.Model methods (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.
  • Expand the DEVELOPMENT.md docs-building section: installing the docs dependency group, output location, the sphinx-autobuild server, the make docclean caching gotcha (essential for config changes to take effect), scanning warnings, and a note on the peewee/autodoc interaction.

Verification

Clean rebuild (make docclean html):

  • Metric documents all 21 fields; EvalRunner all 8 methods
  • No DoesNotExist / FK-alias / inherited-method noise
  • Build warnings down from 35 → 27 (remaining are pre-existing docstring-markup issues unrelated to this fix)

🤖 Generated with Claude Code

levon003 and others added 2 commits June 12, 2026 17:04
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>
@levon003 levon003 self-assigned this Jun 13, 2026
@levon003 levon003 merged commit ceafd8d into main Jun 13, 2026
3 checks passed
@levon003 levon003 deleted the docs/fix-peewee-attributes-issue-86 branch June 13, 2026 00:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Peewee class attributes don't appear in generated documentation

1 participant