posit-dev / posit-dev/great-docs
Use Pydantic `BaseModel` description for documentation
@has2k1 is already working on this.
Since Aug 4, 2026.
- Dominant language
- Python
- Stars
- 262
- Forks
- 18
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 14
Description
Proposal
There are three main ways to document Pydantic BaseModel fields:
- Using
Field(description="a nice description") - Using
Annotated[T, "a nice description"] - Using docstrings below each field
"""a nice description""".
Example:
from pydantic import BaseModel
class Color(BaseModel):
"""General Color class docstring."""
r: int = Field(description="Amount of red.")
g: Annotated[int, "Amount of green."]
b: int
"""Amount of blue."""
As of now, only option 3 generates documentation with great-docs.
Would it be possible to use the Field(description"...") or the Annotated patterns to generate documentation?
I know Pydantic allows setting the config use_attribute_docstrings so docstrings get turned into field descriptions, but most of my code has descriptions using the Field notation.
If that's technicallly not feasible, would it be possible to at least show all fields of a Pydantic BaseModel in docs, even if they don't have documentation docstrings?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.