pydantic-docs

Common infrastructure to build documentation for the Pydantic projects.

Markdown extension

pydantic-docs provides a Markdown extension, that can be used within mkdocs-material:

# mkdocs.yml
markdown_extensions:
  - pydantic_docs.mdext

Blocks

The Markdown extension provides various custom blocks.

Public traces

The public-trace block can be used to embed an iframe for a Logfire public trace:

Here is an example Logfire trace:

/// public-trace | http://logfire-us.pydantic.dev/public-trace/{uuid}
    title: 'Title for the public trace'
    caption: 'prepend'
///

Available options:

• title: The title to set in the caption. Default: no title.
• caption: Whether or where to display the caption:
  • 'off': Don't show the caption (this includes the external link to the public trace).
  • 'prepend': Show the caption before the iframe.
  • 'append': Show the caption after the iframe (the default).
• loading: The loading iframe attribute (default: lazy).

Version changes

Similar to the Sphinx directives, four blocks are available to describe version changes:

• version-added:

  • Block:

    /// version-added | v1
    Added the `foo` parameter.
    ///

  • Rendered:

    

• version-changed:

  • Block:

    /// version-changed | v1
    `Foo` is now implemented as a class.
    
    This shouldn't affect you.
    ///

  • Rendered:

    

• version-deprecated:

  • Block:

    /// version-deprecated | v1
    The `foo` parameter is deprecated.
    ///

  • Rendered:

    

• deprecated-removed:

  • Block:

    /// version-added | v1 v2
    ///

  • Rendered: