Pydantic support

[RothNRK]

Hello, great project. Really appreciate the work.

Do you expect that mkdocstring will support Pydantic models? If so when do you hope to offer that functionality?

Thank you

[pawamoy]

Hello, thanks for the kind words ❤️ !

Yes, I'm planning to add support for Pydantic models 🙂
Right now I'm finishing up the documentation for the Insiders program, then the priority is to improve the current docs, and after that bug fixes and features 😄

[maxschulz-COL]

Hey! Also just wanted to say great project! 🚀 Very much appreciated.

Found this thread when looking for support for Pydantic models, and I would love to express support for the idea of a pydantic extension/handling.

Is there anything one could do to help for it to arrive faster? Even support writing it :)?

Let me know, thanks!

[pawamoy]

Thank you for the kind words 🥰

The two most helpful things you could do are, in no particular order:

• show me how you use Pydantic models, and how they should be supported in mkdocstrings, especially: what info should we retrieve, and how should we display it. Text is good, mockups would be amazing! But really I just want to understand what "Pydantic support" means for interested users 🙂
• more generally, sponsor me through GitHub or Ko-Fi. I'm currently not employed, and trying to make a living off open source. I have 20x more time than before to work on mkdocs-related projects, but there's still so much to do (lots of features and ideas). Sponsoring me would help me to continue this way, rather than going back to being employed and having almost no time for mkdocstrings 🙇

[maxschulz-COL]

Thanks for the prompt reply!

Our team is currently working on another open source tool which I can share with you as soon it is actually public (a few weeks from now). Then it will be completely clear how we use pydantic for instance. For the moment, here are some general considerations:

• there is already a tool for sphinx that does a pretty good job: https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html#default-configuration
• in the default example, some key things are done with a pydantic model: provision of JSON schema, documentation of fields, config and validators --> subtle but very cool: field_with_constraints_and_description only has a Field description, which gets translated into the documentation
• the default example is also compared to the standard sphinx output --> it becomes immediately clear why the pydantic extension helps the documentation of the model. Currently the output of mkdocstrings would look even less useful, as it is mostly empty.

Hence instead of providing mock-up I would say:

• the same information as in the sphinx extension, but in the style of mkdocstrings would completely suffice
• an MVP that would make us very content already is a focus on the fields and their description

Important additional consideration:

• shown somewhat in the very last example (generic-model), it would be cool if a nested pydantic structures would be possible to be automatically recognised and interlinked:

from typing import Union
from pydantic import Field, BaseModel
from typing_extensions import Annotated


class A(BaseModel):
    """Some model."""
    foo: int
    type: str

class B(BaseModel):
    """Some model."""
    foo: int
    type: str

ABType = Annotated[
    Union[A, B],
    Field(
        discriminator="type",
        description="Component that is similar and can be used in `C`.",
    ),
]
class C(BaseModel):
    """Some model."""
    fee: ABType
    type: str

It would be amazing if the documentation produced from the above would be above to handle ABType:

• make ABType clickable in C and then have its own section with the description, then in turn have A and B clickable so that ultimately a user could get from C via ABType to A and B.
• and also: just transfer the description of ABType into the field documentation of fee (in C)

Hope that makes sense 😅 !

As for sponsoring, I am starting a discussion and will see what is possible :)

[pawamoy]

Thanks, that's awesome! And thanks for considering becoming a sponsor 🙂 Note that such a feature will probably land in the $1000/month funding goal (which means sponsors will get immediate access, and the feature will become available to everyone when the goal is reached).

[pawamoy]

First prototype available to sponsors 🙂 https://mkdocstrings.github.io/griffe-pydantic/
It's still very experimental ⚠️