Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hunyadi/sphinx_doc
Enrich Sphinx documentation with Python type information
https://github.com/hunyadi/sphinx_doc
Last synced: about 16 hours ago
JSON representation
Enrich Sphinx documentation with Python type information
- Host: GitHub
- URL: https://github.com/hunyadi/sphinx_doc
- Owner: hunyadi
- License: mit
- Created: 2024-11-30T22:33:23.000Z (22 days ago)
- Default Branch: master
- Last Pushed: 2024-12-15T18:11:30.000Z (7 days ago)
- Last Synced: 2024-12-15T18:16:49.829Z (7 days ago)
- Language: Python
- Size: 14.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
## Installation
This package is [published to PyPI](https://pypi.org/project/python-sphinx-doc/).
```sh
pip install --upgrade python-sphinx-doc
```
## 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.