{"id":23397356,"url":"https://github.com/hunyadi/sphinx_doc","last_synced_at":"2026-02-08T21:02:24.675Z","repository":{"id":268271662,"uuid":"896638357","full_name":"hunyadi/sphinx_doc","owner":"hunyadi","description":"Enrich Sphinx documentation with Python type information","archived":false,"fork":false,"pushed_at":"2024-12-15T18:11:30.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-22T13:23:14.449Z","etag":null,"topics":["documentation-generator","python-typing","sphinx-autodoc"],"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/hunyadi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-30T22:33:23.000Z","updated_at":"2024-12-27T09:59:51.000Z","dependencies_parsed_at":"2024-12-15T18:16:58.222Z","dependency_job_id":"4ee07af9-1dfe-49e7-97d0-5f9354ff960f","html_url":"https://github.com/hunyadi/sphinx_doc","commit_stats":null,"previous_names":["hunyadi/sphinx_doc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunyadi%2Fsphinx_doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunyadi%2Fsphinx_doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunyadi%2Fsphinx_doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunyadi%2Fsphinx_doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunyadi","download_url":"https://codeload.github.com/hunyadi/sphinx_doc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238853614,"owners_count":19541680,"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":["documentation-generator","python-typing","sphinx-autodoc"],"created_at":"2024-12-22T08:17:36.214Z","updated_at":"2025-10-29T16:31:54.722Z","avatar_url":"https://github.com/hunyadi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Enrich Sphinx documentation with Python type information\n\nThis extension to Sphinx [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) enriches class member variable and function parameter lists with type information extracted from Python type annotations.\n\nRefer to the [Sphinx HTML output](https://hunyadi.github.io/sphinx_doc/) for a live demonstration.\n\n## Usage\n\n1. Ensure that you have type hints in all your classes, functions and methods.\n2. Add description to your classes, functions and methods as a doc-string.\n3. Use `:param name: text` to assign a description to member variables and function parameters.\n4. Register `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature`.\n5. Enjoy how type information is automatically injected in the doc-string on `make html`.\n\n## Minimalistic example\n\nThe following code shows how to hook `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature` in Sphinx's `conf.py`:\n\n```python\nfrom sphinx.application import Sphinx\nfrom sphinx_doc.autodoc import Processor, include_special\n\ndef setup(app: Sphinx) -\u003e None:\n    processor = Processor()\n    app.connect(\"autodoc-process-docstring\", processor.process_docstring)\n    app.connect(\"autodoc-before-process-signature\", processor.process_signature)\n    app.connect(\"autodoc-skip-member\", include_special)\n```\n\nRefer to the [published sample](https://github.com/hunyadi/sphinx_doc/blob/master/doc/conf.py) for a more detailed example how to use this extension with Sphinx.\n\n## Installation\n\nThis package is [published to PyPI](https://pypi.org/project/python-sphinx-doc/).\n\n```sh\npip install --upgrade python-sphinx-doc\n```\n\n## Motivation\n\nTo pass type information to `autodoc`, you would normally be required to use the [info field list](https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists) items `:param:` and/or `:type:` with explicit type specification:\n\n```python\ndef send_message(\n    sender: str,\n    recipient: str,\n    message_body: str,\n    priority: int = 1,\n) -\u003e int:\n    \"\"\"\n    :param str sender: The person sending the message.\n    :param str recipient: The recipient of the message.\n    :param str message_body: The body of the message.\n    :param priority: The priority of the message, can be a number 1-5.\n    :type priority: integer or None\n    :return: The message identifier.\n    :rtype: int\n    \"\"\"\n```\n\nHowever, a great deal of information is already present in the Python type signature. This extension promotes a more compact parameter definition whereby type information is injected automatically in documentation strings, and you only need to provide description text:\n\n```python\ndef send_message(\n    sender: str,\n    recipient: str,\n    message_body: str,\n    priority: int = 1,\n) -\u003e int:\n    \"\"\"\n    :param sender: The person sending the message.\n    :param recipient: The recipient of the message.\n    :param message_body: The body of the message.\n    :param priority: The priority of the message, can be a number 1-5.\n    :returns: The message identifier.\n    \"\"\"\n```\n\n## Features\n\n* Data-class member variables are published if they have a corresponding `:param ...:` in the class-level doc-string.\n* All enumeration members are published, even if they lack a description.\n* Magic methods (e.g. `__eq__`) are published if they have a doc-string.\n* Multi-line code blocks in doc-strings are converted to syntax-highlighted monospace text.\n* Primary keys in entity classes have extra visuals (e.g. with a symbol 🔑). See [pysqlsync](https://github.com/hunyadi/pysqlsync) for how to define an entity class (using the `@dataclass` syntax) with a primary key (with the type hint `PrimaryKey[T]`).\n* Type aliases are substituted even if [Postponed Evaluation of Annotations (PEP 563)](https://peps.python.org/pep-0563/) is turned off.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunyadi%2Fsphinx_doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunyadi%2Fsphinx_doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunyadi%2Fsphinx_doc/lists"}