{"id":6528,"library":"autodoc-pydantic","title":"autodoc-pydantic","description":"autodoc-pydantic is a Sphinx extension that seamlessly integrates Pydantic models into Sphinx documentation. It automatically generates documentation for model fields, validators, and configurations, enhancing the standard Sphinx autodoc capabilities for data models. The current version is 2.2.0, with an active development cycle and regular updates.","status":"active","version":"2.2.0","language":"python","source_language":"en","source_url":"https://github.com/mansenfranzen/autodoc_pydantic","tags":["sphinx","pydantic","documentation","autodoc","api-documentation","data-models"],"install":[{"cmd":"pip install autodoc-pydantic sphinx pydantic","lang":"bash","label":"Install with core dependencies"}],"dependencies":[{"reason":"Core documentation generation framework, autodoc-pydantic is a Sphinx extension.","package":"sphinx","optional":false},{"reason":"Library for which this extension provides documentation support. Works with both Pydantic v1 and v2, but has different internal handling.","package":"pydantic","optional":false}],"imports":[{"note":"autodoc-pydantic is enabled by adding its module name as a string to the `extensions` list in Sphinx's `conf.py`. There are no direct Python symbols usually imported by end-users.","wrong":"extensions = ['autodoc_pydantic.plugin']","symbol":"autodoc_pydantic (Sphinx Extension)","correct":"# In conf.py, inside the project's source directory:\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon', # Or other docstring parsing extensions\n    'autodoc_pydantic'\n]"}],"quickstart":{"code":"# 1. Install dependencies: pip install autodoc-pydantic sphinx pydantic\n\n# 2. Initialize a Sphinx project (e.g., using 'sphinx-quickstart')\n\n# 3. Modify conf.py:\n#    Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to the extensions list.\n#    Example conf.py snippet:\n#    extensions = [\n#        'sphinx.ext.autodoc',\n#        'sphinx.ext.napoleon', # For Google/NumPy style docstrings\n#        'autodoc_pydantic'\n#    ]\n\n# 4. Create a Python file (e.g., 'my_models.py'):\n#    from pydantic import BaseModel, Field\n#\n#    class User(BaseModel):\n#        \"\"\"Represents a user in the system.\"\"\"\n#        name: str = Field(..., description=\"The user's full name\")\n#        age: int = Field(default=18, ge=0, description=\"The user's age\")\n\n# 5. Create an RST or Markdown file (e.g., 'models.rst'):\n#    .. automodule:: my_models\n#       :members:\n#\n#    .. autodoc_pydantic_model:: my_models.User\n#       :model-show-json: False\n#       :model-show-config-summary: False\n\n# 6. Build your documentation: make html (or sphinx-build -b html . _build)","lang":"python","description":"To integrate autodoc-pydantic, first create a Sphinx project. Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to your `extensions` list in `conf.py`. Define your Pydantic models in Python modules. Then, use Sphinx's `automodule` combined with autodoc-pydantic's specific directives (e.g., `autodoc_pydantic_model`, `autodoc_pydantic_field`) in your documentation files to generate detailed API documentation for your Pydantic models."},"warnings":[{"fix":"Consult the official migration guide for autodoc-pydantic v2.0.0. For example, `autodoc_pydantic_model_show_config` was renamed to `autodoc_pydantic_model_show_json`, and `autodoc_pydantic_model_show_config_summary` was removed.","message":"Version 2.0.0 introduced significant breaking changes in configuration options to align with Pydantic v2 and refine features. Many `autodoc_pydantic_*` settings were renamed, removed, or had their default behavior altered.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your `conf.py` includes `sphinx.ext.autodoc`, for instance: `extensions = ['sphinx.ext.autodoc', 'autodoc_pydantic']`.","message":"For autodoc-pydantic's directives to function correctly, `sphinx.ext.autodoc` must be present in your `extensions` list in `conf.py`. Without it, Pydantic model documentation will fail or appear incomplete.","severity":"gotcha","affected_versions":"All"},{"fix":"If you wish to control this behavior, set `autodoc_pydantic_field_show_description = False` in your `conf.py` or explore other `autodoc_pydantic_field_show_...` options to fine-tune how field descriptions are presented.","message":"autodoc-pydantic automatically uses the `description` argument of Pydantic's `Field` as the field's docstring. This might lead to redundant or undesired output if you're also providing explicit docstrings or using other methods.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your autodoc-pydantic version is compatible with your installed Pydantic version (v2.0.0+ is recommended for Pydantic v2). Review your autodoc-pydantic configurations after a Pydantic version change, as some displays or features might have altered.","message":"When using Pydantic v1 vs. Pydantic v2, autodoc-pydantic adapts its behavior. If you switch Pydantic versions, especially upgrading from v1 to v2, your documentation output might change or require configuration adjustments.","severity":"gotcha","affected_versions":"All (during Pydantic version transitions)"}],"env_vars":null,"search_vec":"'2.2.0':42 'activ':45 'api':56 'api-document':55 'autodoc':2,5,33,54 'autodoc-pydant':1,4 'automat':20 'capabl':34 'configur':28 'current':39 'cycl':47 'data':36,59 'data-model':58 'develop':46 'document':18,22,53,57 'enhanc':29 'extens':10 'field':25 'generat':21 'integr':13 'model':15,24,37,60 'pydant':3,6,14,52 'regular':49 'seamless':12 'sphinx':9,17,32,51 'standard':31 'updat':50 'valid':26 'version':40","created_at":"2026-04-15T18:31:44.461383+00:00","updated_at":"2026-04-15T21:34:50.583110+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mansenfranzen/autodoc_pydantic","docs":"https://github.com/mansenfranzen/autodoc_pydantic","changelog":null,"pypi":"https://pypi.org/project/autodoc-pydantic/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}