posit-dev / posit-dev/great-docs

Use Pydantic `BaseModel` description for documentation

Open
#281 0 comments 0 reactions 1 assignee View on GitHub

@has2k1 is already working on this.

Since Aug 4, 2026.

Difficulty: [3] Advanced Effort: [2] Medium Priority: [3] High Type: ★ Enhancement
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:

  1. Using Field(description="a nice description")
  2. Using Annotated[T, "a nice description"]
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.