A command-line tool for generating Python docstrings using Concrete Syntax Trees (CST).
py-docstrings analyzes Python source code with LibCST and inserts docstrings while preserving
original formatting, comments, and structure. py-docstrings uses Concrete Syntax Trees, which
retain the exact structure of the original source code. The primary interface is the CLI, with a
few different options depending upon use.
pip install py-docstringsTo generate docstrings directly in a file:
docgen main.pyTo check for missing docstrings without modifying files:
docgen main.py --check-
--recursiveRecursively process Python files in a directory. -
--verboseDisplay information about processed files. -
--fullGenerate a more complete numpy-style docstring with more attributes.
def add(a, b):
return a + bdef add(a, b):
"""Summarize the function in one line.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`. For functions (also method and module),
there should be no blank lines after closing the docstring.
Parameters
----------
var1 : array_like
Array_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array.
*args : iterable
Other arguments.
Returns
-------
describe : type
Explanation of return value named `describe`.
out : type
Explanation of `out`.
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a = [1, 2, 3]
>>> print([x + 3 for x in a])
[4, 5, 6]
"""
return a + b- Top-level functions
- Classes
- Class methods
Existing docstrings are not overwritten.
Planned improvements include:
- Docstrings include actual function arguments
- Generate docstring for specific functions/classes in a module
MIT License