Metadata-Version: 2.4
Name: docstrings2pep727
Version: 0.3.0
Summary: Move documentation from docstrings to PEP 727 type annotations.
Author-Email: Timothée Mazzucotelli <dev@pawamoy.fr>
License-Expression: ISC
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Project-URL: Homepage, https://pawamoy.github.io/docstrings2pep727
Project-URL: Documentation, https://pawamoy.github.io/docstrings2pep727
Project-URL: Changelog, https://pawamoy.github.io/docstrings2pep727/changelog
Project-URL: Repository, https://github.com/pawamoy/docstrings2pep727
Project-URL: Issues, https://github.com/pawamoy/docstrings2pep727/issues
Project-URL: Discussions, https://github.com/pawamoy/docstrings2pep727/discussions
Project-URL: Gitter, https://gitter.im/docstrings2pep727/community
Project-URL: Funding, https://github.com/sponsors/pawamoy
Requires-Python: >=3.11
Requires-Dist: libcst>=1.0.1
Requires-Dist: griffe>=2.0
Requires-Dist: typing-extensions>=4.8
Description-Content-Type: text/markdown

# docstrings2pep727

[![ci](https://github.com/pawamoy/docstrings2pep727/workflows/ci/badge.svg)](https://github.com/pawamoy/docstrings2pep727/actions?query=workflow%3Aci)
[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://pawamoy.github.io/docstrings2pep727/)
[![pypi version](https://img.shields.io/pypi/v/docstrings2pep727.svg)](https://pypi.org/project/docstrings2pep727/)
[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#docstrings2pep727:gitter.im)

Move documentation from docstrings to PEP 727 type annotations.

## Installation

```bash
pip install docstrings2pep727
```

With [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool install docstrings2pep727
```


## Usage


Add `typing-extensions>=4.8` to the project that runs the transformed code. The output imports `Doc` from `typing_extensions`.


Preview changes before editing files:


```bash
docstrings2pep727 diff src/
```


Rewrite one or more Python files or directories:


```bash
docstrings2pep727 format src/ tests/
```


Use `check` in CI. It leaves files unchanged and exits with status 1 if changes are needed.


```bash
docstrings2pep727 check src/
```


Each subcommand detects Google, NumPy, and Sphinx docstrings. To choose a style, add `--style google`, `--style numpy`, or `--style sphinx` after the subcommand.


```bash
docstrings2pep727 format --style google src/
```


The transformation moves descriptions for annotated parameters, returns, yields, receives, and attributes into `Annotated[..., Doc(...)]`.


It keeps prose and unsupported sections, such as `Raises`, in docstrings. It keeps a section if any item cannot be moved.


## Sponsors

<!-- sponsors-start -->
<!-- sponsors-end -->
