{"id":1719,"library":"sphinx-autodoc-typehints","title":"Sphinx Autodoc Typehints","description":"sphinx-autodoc-typehints is a Sphinx extension that provides full support for type hints (PEP 484) in the documentation generated by `sphinx.ext.autodoc`. It parses type annotations from Python code and renders them beautifully in reStructuredText or Markdown output. The current version is 3.9.11, and it follows a minor release cadence driven by bug fixes and compatibility with new Sphinx or Python versions.","status":"active","version":"3.9.11","language":"en","source_language":"en","source_url":"https://github.com/tox-dev/sphinx-autodoc-typehints","tags":["sphinx","documentation","autodoc","type-hints","pep-484"],"install":[{"cmd":"pip install sphinx-autodoc-typehints","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false},{"reason":"Requires Python 3.12 or newer. Previous versions (e.g., <3.0.0) supported older Python versions.","package":"Python","optional":false}],"imports":[{"note":"Sphinx extensions are enabled by adding their string name to the 'extensions' list in conf.py. `sphinx.ext.autodoc` must be loaded *before* `sphinx_autodoc_typehints` to function correctly.","wrong":"extensions = ['sphinx_autodoc_typehints', 'sphinx.ext.autodoc']","symbol":"sphinx_autodoc_typehints","correct":"extensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_autodoc_typehints'\n]"}],"quickstart":{"code":"import os\n\n# conf.py example\n\n# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath.\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Project'\ncopyright = '2024, Author Name'\nauthor = 'Author Name'\nrelease = '0.1'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_autodoc_typehints' # Add this extension\n]\n\n# Optional: Configure the extension\ntypehints_fully_qualified = False # This option was removed in v3.0.0 (example of a common mistake for older configs)\ntypehints_document_rtype = True # Explicitly document return types\n\n# Example Python module (my_module.py)\n# def greet(name: str, age: int = 30) -> str:\n#     \"\"\"Greets a person.\n#\n#     :param name: The name of the person.\n#     :param age: The age of the person.\n#     :return: A greeting message.\n#     \"\"\"\n#     return f\"Hello, {name}! You are {age} years old.\"\n","lang":"python","description":"To quickly integrate `sphinx-autodoc-typehints` into your project, ensure `sphinx.ext.autodoc` is enabled in your `conf.py` first, then add `'sphinx_autodoc_typehints'` to the `extensions` list. This snippet shows a minimal `conf.py` setup, including common configuration options. Create a Python module with type-hinted functions/classes, then use `automodule` directives in your `.rst` files to generate documentation."},"warnings":[{"fix":"Upgrade your Python environment to 3.12+, or pin the library version to `<3` (e.g., `pip install 'sphinx-autodoc-typehints<3'`).","message":"Version 3.0.0 and newer require Python 3.12+ and Sphinx 6.0+. If you are on an older Python version, you must use `sphinx-autodoc-typehints<3`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove these options from your `conf.py`. The `typehints_fully_qualified` option functionality is largely superseded by Sphinx's own type resolution improvements.","message":"Configuration options `always_document_param_types` and `typehints_fully_qualified` were removed in version 3.0.0. Using them will result in a Sphinx warning about unknown configuration values and these settings will be ignored.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure `extensions = ['sphinx.ext.autodoc', 'sphinx_autodoc_typehints']` (or similar order) is used in your `conf.py`.","message":"`sphinx.ext.autodoc` must be enabled and loaded *before* `sphinx_autodoc_typehints` in your `conf.py` `extensions` list for type hints to be correctly processed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you wish to continue documenting return types, explicitly set `typehints_document_rtype = True` in your `conf.py`.","message":"The default value for the `typehints_document_rtype` configuration option changed from `True` to `False` in version 3.0.0. This means return types are no longer documented by default.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}