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:
- Flag missing docstrings:
test is missing a docstring test.say_hello is missing a docstring - 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__ """ - 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}!')
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: 1.0.0
hooks:
- id: docstringifyBy 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: 1.0.0
hooks:
- id: docstringify
args: [--threshold=0.75]If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the --suggest-changes argument, 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: 1.0.0
hooks:
- id: docstringify
args: [--suggest-changes=numpydoc]Use --make-changes 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: 1.0.0
hooks:
- id: docstringify
args: [--make-changes=google]If you want the changes to be made in place, change --make-changes to --make-changes-inplace – make sure you only operate on files that are in version control with this setting. Here, we ask for numpydoc-style docstring suggestions:
- repo: https://github.com/stefmolin/docstringify
rev: 1.0.0
hooks:
- id: docstringify
args: [--make-changes-inplace=numpydoc]Be sure to check out the pre-commit documentation for additional configuration options.
First, install the docstringify package from PyPI:
$ python -m pip install docstringifyThen, use the docstringify entry point on the file(s) of your choice:
$ docstringify /path/to/file [/path/to/another/file]Run docstringify --help for more information.
First, install the docstringify package from PyPI:
$ python -m pip install docstringifyThen, 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 docstringIf 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.pyIf 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.pyPlease consult the contributing guidelines.