| Name | python-sphinx-doc JSON |
| Version |
0.1
JSON |
| download |
| home_page | None |
| Summary | Enrich Sphinx documentation with Python type information |
| upload_time | 2024-12-15 18:05:00 |
| maintainer | None |
| docs_url | None |
| author | Levente Hunyadi |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Enrich Sphinx documentation with Python type information
This 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.
Refer to the [Sphinx HTML output](https://hunyadi.github.io/sphinx_doc/) for a live demonstration.
## Usage
1. Ensure that you have type hints in all your classes, functions and methods.
2. Add description to your classes, functions and methods as a doc-string.
3. Use `:param name: text` to assign a description to member variables and function parameters.
4. Register `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature`.
5. Enjoy how type information is automatically injected in the doc-string on `make html`.
## Minimalistic example
The following code shows how to hook `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature` in Sphinx's `conf.py`:
```python
from sphinx.application import Sphinx
from sphinx_doc.autodoc import Processor, include_special
def setup(app: Sphinx) -> None:
processor = Processor()
app.connect("autodoc-process-docstring", processor.process_docstring)
app.connect("autodoc-before-process-signature", processor.process_signature)
app.connect("autodoc-skip-member", include_special)
```
Refer 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.
## Motivation
To 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:
```python
def send_message(
sender: str,
recipient: str,
message_body: str,
priority: int = 1,
) -> int:
"""
:param str sender: The person sending the message.
:param str recipient: The recipient of the message.
:param str message_body: The body of the message.
:param priority: The priority of the message, can be a number 1-5.
:type priority: integer or None
:return: The message identifier.
:rtype: int
"""
```
However, 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:
```python
def send_message(
sender: str,
recipient: str,
message_body: str,
priority: int = 1,
) -> int:
"""
:param sender: The person sending the message.
:param recipient: The recipient of the message.
:param message_body: The body of the message.
:param priority: The priority of the message, can be a number 1-5.
:returns: The message identifier.
"""
```
## Features
* Data-class member variables are published if they have a corresponding `:param ...:` in the class-level doc-string.
* All enumeration members are published, even if they lack a description.
* Magic methods (e.g. `__eq__`) are published if they have a doc-string.
* Multi-line code blocks in doc-strings are converted to syntax-highlighted monospace text.
* 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]`).
* Type aliases are substituted even if [Postponed Evaluation of Annotations (PEP 563)](https://peps.python.org/pep-0563/) is turned off.
Raw data
{
"_id": null,
"home_page": null,
"name": "python-sphinx-doc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Levente Hunyadi",
"author_email": "hunyadi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b0/0c/05c20bb2bbad0ea214bab33b97ab71f69d4b5f33732efeb5ec2e61569e69/python_sphinx_doc-0.1.tar.gz",
"platform": null,
"description": "# Enrich Sphinx documentation with Python type information\r\n\r\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.\r\n\r\nRefer to the [Sphinx HTML output](https://hunyadi.github.io/sphinx_doc/) for a live demonstration.\r\n\r\n## Usage\r\n\r\n1. Ensure that you have type hints in all your classes, functions and methods.\r\n2. Add description to your classes, functions and methods as a doc-string.\r\n3. Use `:param name: text` to assign a description to member variables and function parameters.\r\n4. Register `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature`.\r\n5. Enjoy how type information is automatically injected in the doc-string on `make html`.\r\n\r\n## Minimalistic example\r\n\r\nThe following code shows how to hook `Processor` to the events `autodoc-process-docstring` and `autodoc-before-process-signature` in Sphinx's `conf.py`:\r\n\r\n```python\r\nfrom sphinx.application import Sphinx\r\nfrom sphinx_doc.autodoc import Processor, include_special\r\n\r\ndef setup(app: Sphinx) -> None:\r\n processor = Processor()\r\n app.connect(\"autodoc-process-docstring\", processor.process_docstring)\r\n app.connect(\"autodoc-before-process-signature\", processor.process_signature)\r\n app.connect(\"autodoc-skip-member\", include_special)\r\n```\r\n\r\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.\r\n\r\n## Motivation\r\n\r\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:\r\n\r\n```python\r\ndef send_message(\r\n sender: str,\r\n recipient: str,\r\n message_body: str,\r\n priority: int = 1,\r\n) -> int:\r\n \"\"\"\r\n :param str sender: The person sending the message.\r\n :param str recipient: The recipient of the message.\r\n :param str message_body: The body of the message.\r\n :param priority: The priority of the message, can be a number 1-5.\r\n :type priority: integer or None\r\n :return: The message identifier.\r\n :rtype: int\r\n \"\"\"\r\n```\r\n\r\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:\r\n\r\n```python\r\ndef send_message(\r\n sender: str,\r\n recipient: str,\r\n message_body: str,\r\n priority: int = 1,\r\n) -> int:\r\n \"\"\"\r\n :param sender: The person sending the message.\r\n :param recipient: The recipient of the message.\r\n :param message_body: The body of the message.\r\n :param priority: The priority of the message, can be a number 1-5.\r\n :returns: The message identifier.\r\n \"\"\"\r\n```\r\n\r\n## Features\r\n\r\n* Data-class member variables are published if they have a corresponding `:param ...:` in the class-level doc-string.\r\n* All enumeration members are published, even if they lack a description.\r\n* Magic methods (e.g. `__eq__`) are published if they have a doc-string.\r\n* Multi-line code blocks in doc-strings are converted to syntax-highlighted monospace text.\r\n* Primary keys in entity classes have extra visuals (e.g. with a symbol \ud83d\udd11). 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]`).\r\n* Type aliases are substituted even if [Postponed Evaluation of Annotations (PEP 563)](https://peps.python.org/pep-0563/) is turned off.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enrich Sphinx documentation with Python type information",
"version": "0.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "287ec38b4abefdd2d2231429a25d7cfab8bfec9fd2b9e92ef9267be7fbdb25e7",
"md5": "848f8bfa7998396b3ec91ef528e261ae",
"sha256": "13f35bae42d39b92bf1de5578e38b49a74a2a58ed0d61e85a46ccec308fd9a3b"
},
"downloads": -1,
"filename": "python_sphinx_doc-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "848f8bfa7998396b3ec91ef528e261ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8436,
"upload_time": "2024-12-15T18:04:58",
"upload_time_iso_8601": "2024-12-15T18:04:58.405733Z",
"url": "https://files.pythonhosted.org/packages/28/7e/c38b4abefdd2d2231429a25d7cfab8bfec9fd2b9e92ef9267be7fbdb25e7/python_sphinx_doc-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b00c05c20bb2bbad0ea214bab33b97ab71f69d4b5f33732efeb5ec2e61569e69",
"md5": "5891d64c4e06f564f3af6778f9a4ad08",
"sha256": "4b985e57d3d77e970ee5b5d9b53e7f262f70c693ebe9e2aa629106adeeb4a6ed"
},
"downloads": -1,
"filename": "python_sphinx_doc-0.1.tar.gz",
"has_sig": false,
"md5_digest": "5891d64c4e06f564f3af6778f9a4ad08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8064,
"upload_time": "2024-12-15T18:05:00",
"upload_time_iso_8601": "2024-12-15T18:05:00.937224Z",
"url": "https://files.pythonhosted.org/packages/b0/0c/05c20bb2bbad0ea214bab33b97ab71f69d4b5f33732efeb5ec2e61569e69/python_sphinx_doc-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 18:05:00",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "python-sphinx-doc"
}
