Skip to content

Autopopulate API contents if none provided#425

Open
cliffckerr wants to merge 2 commits into
machow:mainfrom
sciris:autopopulate-contents
Open

Autopopulate API contents if none provided#425
cliffckerr wants to merge 2 commits into
machow:mainfrom
sciris:autopopulate-contents

Conversation

@cliffckerr
Copy link
Copy Markdown

@cliffckerr cliffckerr commented May 17, 2026

Summary

For small Python packages, you typically want to document the entire API, and don't need to do any customization in terms of ordering. But currently, quartodoc requires the API contents to be explicitly listed in _quarto.yml.

This PR makes it so if no contents are provided to quartodoc, it will behave as if every source file was listed.

This behavior was copied from mkdocstrings-python, since this was the only feature I could find that mkdocstrings had that quartodoc seemed to lack :)

Details

  • Auto-populate a section's contents from the configured package when none is provided, so users can omit explicit content lists for full-package documentation.
  • Walks the package's submodule search locations for *.py files (excluding __init__.py and __pycache__) and generates an Auto entry per module.
  • Adds a validator on Page.contents to reject empty page contents, and re-exports validator from the pydantic v1/v2 compatibility shim.
  • Documents the new behavior in docs/get-started/overview.qmd.

Test plan

  • Build a site with a quartodoc config whose section omits contents and confirm modules are auto-discovered.
  • Build a site with explicit contents and confirm behavior is unchanged.
  • Confirm a warning is logged when a section has no contents and no package is configured.
  • Confirm a Page with empty contents raises a validation error.
  • Verify the new docs section renders correctly in docs/get-started/overview.qmd.

(NB: feature implemented with the help of Claude)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant