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.

Render field examples #186

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions