Render field examples

[azmeuk]

pydantic has a examples parameter. However it seems to not be rendered by autodoc_pydantic and I could not find documentation about this.

I suggest to render the field examples in the documentation.

[mansenfranzen]

Hi @azmeuk,

thanks for raising the feature request!

I think this could be a sensible addition to improve documentation on pydantic models. I would like to understand your use case and the added value more clearly. Could you go into more detail here, please?
Also, can you could provide a concrete pydantic model along with a proposal about how the example parameters should be documented? Thanks!

[azmeuk]

Sure. I mainly use autodoc_pydantic to document configuration settings.
For instance I have one class that configure a LDAP authentication for my application. As LDAP notions are pretty abstruses, I would like to provide examples so users can guess what values are expected. Currently, I manually provide example in the attribute docstrings:

class LDAPSettings(BaseSettings):
    """
    Settings related to the LDAP backend.
    """

    URI: str
    """
    The LDAP server URI. For example:
        - ``"ldap://localhost"``
        - ``"ldaps://ldap.mydomain.tld"``
    """

    ROOT_DN: str
    """
    The LDAP root DN. For example:
        - ``"dc=mydomain,dc=tld"``
    """

    BIND_DN: str
    """
    The LDAP bind DN. For example:
        - ``"cn=admin,dc=mydomain,dc=tld"``
    """

    BIND_PW: str
    """
    The LDAP bind password.
    """

    TIMEOUT: float = 0.0
    """
    The LDAP connection timeout.
    """

    USER_BASE: str
    """
    The LDAP node under which users will be looked for and saved.
    For example ``"ou=users,dc=mydomain,dc=tld"``.
    """

    USER_CLASS: str | List[str] = "inetOrgPerson"
    """
    The object class to use for creating new users. For example:
        - ``"inetOrgPerson"``
        - ``["inetOrgPerson", "posixAccount"]``
    """

    USER_RDN: str = "uid"
    """
    The attribute to identify an object in the User DN.
    For example:
        - ``"uid"``
        - ``"cn"``
    """

    USER_FILTER: str
    """
    Filter to match users on sign in.
    Jinja syntax is supported and a ``login`` variable is available,
    containing the value passed in the login field.
    For example:
        - ``(|(uid={{ login }})(mail={{ login }}))``
    """

    GROUP_BASE: str
    """
    The LDAP node under which groups will be looked for and saved.
    For example:
        - ``"ou=groups,dc=mydomain,dc=tld"``.
    """

    GROUP_CLASS: str = "groupOfNames"
    """
    The object class to use for creating new groups.
    For example:
        - ``"groupOfNames"``
        - ``"posixGroup"``
    """

    GROUP_RDN: str = "cn"
    """
    The attribute to identify an object in the Group DN.
    """

    GROUP_NAME_ATTRIBUTE: str = "cn"
    """
    The attribute to use to identify a group
    """

In that situation we could have instead:

    URI: str = Field(examples=["ldap://localhost", "ldaps://ldap.mydomain.tld"])
    """
    The LDAP server URI.
    """

Using docstrings to document examples is fine, but if autodoc_pydantic would render them, this would have the benefit to uniformize the rendering and allow me to really use the examples attribute.
The examples attribute is convenient to display to users for example as placeholders in HTML forms.