Formats docstrings to follow PEP 257.
docformatter currently automatically formats docstrings to follow a subset of the PEP 257 conventions. Below are the relevant items quoted from PEP 257.
- For consistency, always use triple double quotes around docstrings.
- Triple quotes are used even though the string fits on one line.
- Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.
- Unless the entire docstring fits on a line, place the closing quotes on a line by themselves.
docformatter also handles some of the PEP 8 conventions.
- Don't write string literals that rely on significant trailing whitespace. Such trailing whitespace is visually indistinguishable and some editors (or more recently, reindent.py) will trim them.
From pip:
$ pip install --upgrade docformatter
After running:
$ docformatter --in-place example.py
this code
""" Here are some examples.
This module docstring should be dedented."""
def launch_rocket():
"""Launch
the
rocket. Go colonize space."""
def factorial(x):
'''
Return x factorial.
This uses math.factorial.
'''
import math
return math.factorial(x)
def print_factorial(x):
"""Print x factorial"""
print(factorial(x))
def main():
"""Main
function"""
print_factorial(5)
if factorial(10):
launch_rocket()gets formatted into this
"""Here are some examples.
This module docstring should be dedented.
"""
def launch_rocket():
"""Launch the rocket.
Go colonize space.
"""
def factorial(x):
"""Return x factorial.
This uses math.factorial.
"""
import math
return math.factorial(x)
def print_factorial(x):
"""Print x factorial."""
print(factorial(x))
def main():
"""Main function."""
print_factorial(5)
if factorial(10):
launch_rocket()Below is the help output:
usage: docformatter [-h] [-i | -c] [-r] [--wrap-summaries length]
[--wrap-descriptions length] [--blank]
[--pre-summary-newline] [--make-summary-multi-line]
[--force-wrap] [--range line line] [--version]
files [files ...]
Formats docstrings to follow PEP 257.
positional arguments:
files files to format or '-' for standard in
optional arguments:
-h, --help show this help message and exit
-i, --in-place make changes to files instead of printing diffs
-c, --check only check and report incorrectly formatted files
-r, --recursive drill down directories recursively
--wrap-summaries length
wrap long summary lines at this length; set to 0 to
disable wrapping (default: 79)
--wrap-descriptions length
wrap descriptions at this length; set to 0 to disable
wrapping (default: 72)
--blank add blank line after description
--pre-summary-newline
add a newline before the summary of a multi-line
docstring
--make-summary-multi-line
add a newline before and after the summary of a one-
line docstring
--force-wrap force descriptions to be wrapped even if it may result
in a mess
--range line line apply docformatter to docstrings between these lines;
line numbers are indexed at 1
--version show program's version number and exit
Possible exit codes:
- 1 - if any error encountered
- 3 - if any file needs to be formatted (in
--checkmode)
docformatter will wrap descriptions, but only in simple cases. If there is text that seems like a bulleted/numbered list, docformatter will leave the description as is:
- Item one. - Item two. - Item three.
This prevents the risk of the wrapping turning things into a mess. To force
even these instances to get wrapped use --force-wrap.
Bugs and patches can be reported on the GitHub page.