{"id":13494365,"url":"https://github.com/tox-dev/sphinx-autodoc-typehints","last_synced_at":"2025-05-13T18:06:46.329Z","repository":{"id":38107300,"uuid":"42892576","full_name":"tox-dev/sphinx-autodoc-typehints","owner":"tox-dev","description":"Type hints support for the Sphinx autodoc extension","archived":false,"fork":false,"pushed_at":"2025-05-05T20:15:20.000Z","size":603,"stargazers_count":572,"open_issues_count":40,"forks_count":107,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-11T23:33:29.253Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tox-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"tidelift":"pypi/sphinx-autodoc-typehints"}},"created_at":"2015-09-21T20:41:41.000Z","updated_at":"2025-05-05T20:15:23.000Z","dependencies_parsed_at":"2023-09-27T03:08:29.619Z","dependency_job_id":"7aee4051-d700-49f5-bd85-1335444a8c92","html_url":"https://github.com/tox-dev/sphinx-autodoc-typehints","commit_stats":{"total_commits":371,"total_committers":58,"mean_commits":6.396551724137931,"dds":0.6172506738544474,"last_synced_commit":"ea99f28598fe8cc4181c5bcf64b295e310ff4caa"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fsphinx-autodoc-typehints","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fsphinx-autodoc-typehints/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fsphinx-autodoc-typehints/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Fsphinx-autodoc-typehints/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tox-dev","download_url":"https://codeload.github.com/tox-dev/sphinx-autodoc-typehints/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000848,"owners_count":21997441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-07-31T19:01:24.309Z","updated_at":"2025-05-13T18:06:46.310Z","avatar_url":"https://github.com/tox-dev.png","language":"Python","readme":"# sphinx-autodoc-typehints\n\n[![PyPI](https://img.shields.io/pypi/v/sphinx-autodoc-typehints?style=flat-square)](https://pypi.org/project/sphinx-autodoc-typehints/)\n[![Supported Python\nversions](https://img.shields.io/pypi/pyversions/sphinx-autodoc-typehints.svg)](https://pypi.org/project/sphinx-autodoc-typehints/)\n[![Downloads](https://pepy.tech/badge/sphinx-autodoc-typehints/month)](https://pepy.tech/project/sphinx-autodoc-typehints)\n[![check](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml)\n\nThis extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types\nof functions. See an example of the Sphinx render at the\n[pyproject-api docs](https://pyproject-api.readthedocs.io/latest/api.html).\n\nThis allows you to use type hints in a very natural fashion, allowing you to migrate from this:\n\n```python\ndef format_unit(value, unit):\n    \"\"\"\n    Formats the given value as a human readable string using the given units.\n\n    :param float|int value: a numeric value\n    :param str unit: the unit for the value (kg, m, etc.)\n    :rtype: str\n    \"\"\"\n    return f\"{value} {unit}\"\n```\n\nto this:\n\n```python\nfrom typing import Union\n\n\ndef format_unit(value: Union[float, int], unit: str) -\u003e str:\n    \"\"\"\n    Formats the given value as a human readable string using the given units.\n\n    :param value: a numeric value\n    :param unit: the unit for the value (kg, m, etc.)\n    \"\"\"\n    return f\"{value} {unit}\"\n```\n\n## Installation and setup\n\nFirst, use pip to download and install the extension:\n\n```bash\npip install sphinx-autodoc-typehints\n```\n\nThen, add the extension to your `conf.py`:\n\n```python\nextensions = [\"sphinx.ext.autodoc\", \"sphinx_autodoc_typehints\"]\n```\n\n## Options\n\nThe following configuration options are accepted:\n\n- `typehints_fully_qualified` (default: `False`): if `True`, class names are always fully qualified (e.g.\n  `module.for.Class`). If `False`, just the class name displays (e.g. `Class`)\n- `always_document_param_types` (default: `False`): If `False`, do not add type info for undocumented parameters. If\n  `True`, add stub documentation for undocumented parameters to be able to add type info.\n- `always_use_bars_union ` (default: `False`): If `True`, display Union's using the | operator described in PEP 604.\n  (e.g `X` | `Y` or `int` | `None`). If `False`, Unions will display with the typing in brackets. (e.g. `Union[X, Y]`\n  or `Optional[int]`)\n- `typehints_document_rtype` (default: `True`): If `False`, never add an `:rtype:` directive. If `True`, add the\n  `:rtype:` directive if no existing `:rtype:` is found.\n- `typehints_document_rtype_none` (default: `True`): If `False`, never add an `:rtype: None` directive. If `True`, add the `:rtype: None`.\n- `typehints_use_rtype` (default: `True`): Controls behavior when `typehints_document_rtype` is set to `True`. If\n  `True`, document return type in the `:rtype:` directive. If `False`, document return type as part of the `:return:`\n  directive, if present, otherwise fall back to using `:rtype:`. Use in conjunction with\n  [napoleon_use_rtype](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype)\n  to avoid generation of duplicate or redundant return type information.\n- `typehints_defaults` (default: `None`): If `None`, defaults are not added. Otherwise, adds a default annotation:\n\n  - `'comma'` adds it after the type, changing Sphinx’ default look to “**param** (_int_, default: `1`) -- text”.\n  - `'braces'` adds `(default: ...)` after the type (useful for numpydoc like styles).\n  - `'braces-after'` adds `(default: ...)` at the end of the parameter documentation text instead.\n\n- `simplify_optional_unions` (default: `True`): If `True`, optional parameters of type \\\"Union\\[\\...\\]\\\" are simplified\n  as being of type Union\\[\\..., None\\] in the resulting documentation (e.g. Optional\\[Union\\[A, B\\]\\] -\\\u003e Union\\[A, B,\n  None\\]). If `False`, the \\\"Optional\\\"-type is kept. Note: If `False`, **any** Union containing `None` will be\n  displayed as Optional! Note: If an optional parameter has only a single type (e.g Optional\\[A\\] or Union\\[A, None\\]),\n  it will **always** be displayed as Optional!\n- `typehints_formatter` (default: `None`): If set to a function, this function will be called with `annotation` as first\n  argument and `sphinx.config.Config` argument second. The function is expected to return a string with reStructuredText\n  code or `None` to fall back to the default formatter.\n- `typehints_use_signature` (default: `False`): If `True`, typehints for parameters in the signature are shown.\n- `typehints_use_signature_return` (default: `False`): If `True`, return annotations in the signature are shown.\n\n## How it works\n\nThe extension listens to the `autodoc-process-signature` and `autodoc-process-docstring` Sphinx events. In the former,\nit strips the annotations from the function signature. In the latter, it injects the appropriate `:type argname:` and\n`:rtype:` directives into the docstring.\n\nOnly arguments that have an existing `:param:` directive in the docstring get their respective `:type:` directives\nadded. The `:rtype:` directive is added if and only if no existing `:rtype:` is found.\n\n## Compatibility with sphinx.ext.napoleon\n\nTo use [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) with sphinx-autodoc-typehints, make\nsure you load [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) first, **before**\nsphinx-autodoc-typehints. See [Issue 15](https://github.com/tox-dev/sphinx-autodoc-typehints/issues/15) on the issue\ntracker for more information.\n\n## Dealing with circular imports\n\nSometimes functions or classes from two different modules need to reference each other in their type annotations. This\ncreates a circular import problem. The solution to this is the following:\n\n1. Import only the module, not the classes/functions from it\n2. Use forward references in the type annotations (e.g. `def methodname(self, param1: 'othermodule.OtherClass'):`)\n\nOn Python 3.7, you can even use `from __future__ import annotations` and remove the quotes.\n","funding_links":["https://tidelift.com/funding/github/pypi/sphinx-autodoc-typehints"],"categories":["Python","Documentation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Fsphinx-autodoc-typehints","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftox-dev%2Fsphinx-autodoc-typehints","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Fsphinx-autodoc-typehints/lists"}