https://github.com/stefmolin/docstringify
Flag missing docstrings and, optionally, generate them from signatures and type annotations.
https://github.com/stefmolin/docstringify
abstract-syntax-tree ast docstring docstring-generator google-docstring numpydoc pre-commit pre-commit-hook stubs
Last synced: 2 days ago
JSON representation
Flag missing docstrings and, optionally, generate them from signatures and type annotations.
- Host: GitHub
- URL: https://github.com/stefmolin/docstringify
- Owner: stefmolin
- License: mit
- Created: 2025-03-31T03:24:37.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-26T17:18:16.000Z (about 2 months ago)
- Last Synced: 2026-05-10T12:03:01.749Z (about 1 month ago)
- Topics: abstract-syntax-tree, ast, docstring, docstring-generator, google-docstring, numpydoc, pre-commit, pre-commit-hook, stubs
- Language: Python
- Homepage: https://pypi.org/project/docstringify/
- Size: 219 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-pyladies-creations - Docstringify
README
# Docstringify
Flag missing docstrings and, optionally, generate them from signatures and type annotations.
## About
Given a file, `test.py`, with the following contents:
```python
def say_hello(name: str = 'World') -> None:
print(f'Hello, {name}!')
```
You can use Docstringify in three modes:
1. `check` – Flag missing docstrings:
```
test is missing a docstring
test.say_hello is missing a docstring
```
2. `suggest` – Suggest docstring templates based on type annotations:
```
test is missing a docstring
Hint:
"""__description__"""
test.say_hello is missing a docstring
Hint:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
```
3. `edit` – Add docstring templates to source code files:
```python
"""__description__"""
def say_hello(name: str = 'World') -> None:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
print(f'Hello, {name}!')
```
## Usage
### Pre-commit hook
> [!NOTE]
> The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag.
#### Check mode: `docstringify-check`
Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev:
hooks:
- id: docstringify-check
```
By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev:
hooks:
- id: docstringify-check
args: [--threshold=0.75]
```
#### Suggest mode: `docstringify-suggest`
If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
```yaml
- repo: https://github.com/stefmolin/docstringify
rev:
hooks:
- id: docstringify-suggest
args: [--style=stub]
```
#### Edit mode: `docstringify-edit`
Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
```yaml
- repo: https://github.com/stefmolin/docstringify
rev:
hooks:
- id: docstringify-edit
args: [--style=google]
```
If you want the changes to be made in place, add `--overwrite`. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev:
hooks:
- id: docstringify-edit
args: [--overwrite, --style=numpydoc]
```
> [!WARNING]
> Make sure you only operate on files that are in version control if you are using `--overwrite`.
Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
### Command line
First, install the `docstringify` package from PyPI:
```shell
$ python -m pip install docstringify
```
Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:
```shell
$ docstringify check /path/to/file [/path/to/another/file]
```
Run `docstringify --help` for more information.
### Python
First, install the `docstringify` package from PyPI:
```shell
$ python -m pip install docstringify
```
Then, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:
```pycon
>>> from docstringify.traversal import DocstringVisitor
>>> visitor = DocstringVisitor('test.py')
>>> visitor.process_file()
test is missing a docstring
test.say_hello is missing a docstring
```
If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:
```pycon
>>> from docstringify.converters import NumpydocDocstringConverter
>>> from docstringify.traversal import DocstringVisitor
>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
>>> visitor.process_file()
test is missing a docstring
Hint:
"""__description__"""
test.say_hello is missing a docstring
Hint:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
```
To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
```pycon
>>> from docstringify.converters import GoogleDocstringConverter
>>> from docstringify.traversal import DocstringTransformer
>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
>>> transformer.process_file()
test is missing a docstring
test.say_hello is missing a docstring
Docstring templates written to /.../test_docstringify.py
```
If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
```pycon
>>> from docstringify.converters import GoogleDocstringConverter
>>> from docstringify.traversal import DocstringTransformer
>>> transformer = DocstringTransformer(
... 'test.py', converter=GoogleDocstringConverter, overwrite=True
... )
>>> transformer.process_file()
test is missing a docstring
test.say_hello is missing a docstring
Docstring templates written to /.../test.py
```
## Contributing
Please consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).