Flag missing docstrings and, optionally, generate them from signatures and type annotations.
|
|
|
|
|
|
|
|
|
Given a file, test.py, with the following contents:
def say_hello(name: str = 'World') -> None: print(f'Hello, {name}!')
You can use Docstringify in three modes:
-
check– Flag missing docstrings:test is missing a docstring test.say_hello is missing a docstring -
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__ """ -
edit– Add docstring templates to source code files:"""__description__""" def say_hello(name: str = 'World') -> None: """ __description__ Parameters ---------- name : str, default="World" __description__ """ print(f'Hello, {name}!')
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.
Add the following to your .pre-commit-config.yaml file to block commits with missing docstrings before any formatters like ruff:
- repo: https://github.com/stefmolin/docstringify rev: <version> 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:
- repo: https://github.com/stefmolin/docstringify rev: <version> hooks: - id: docstringify-check args: [--threshold=0.75]
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__"""):
- repo: https://github.com/stefmolin/docstringify rev: <version> hooks: - id: docstringify-suggest args: [--style=stub]
Use the edit mode to create a copy of each file with docstring templates. Here, we ask for changes using the Google docstring style:
- repo: https://github.com/stefmolin/docstringify rev: <version> 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 suggestions:
- repo: https://github.com/stefmolin/docstringify rev: <version> 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 for additional configuration options.
First, install the docstringify package from PyPI:
$ 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:
$ docstringify check /path/to/file [/path/to/another/file]
Run docstringify --help for more information.
First, install the docstringify package from PyPI:
$ python -m pip install docstringify
Then, use the DocstringVisitor() class on individual files to see spots where docstrings are missing:
>>> 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:
>>> 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:
>>> 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():
>>> 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
Please consult the contributing guidelines.