A docstring writer for Python files written in Python.
It automatically generates docstrings for functions and classes in Python scripts.
Using the AST (Abstract Syntax Tree), it finds the arguments, attributes, returned/yielded variables and raised exceptions and formats them, mostly following the Google Python Style Guide.
No, because you still have to write descriptions that describe what the functions do. Good documentation shows not only what variables are being used but how and why they are being used as well.
Yes.
Running it:
$ python3 doc_writer.py boop.py stuff.txt
Input:
boop.py
class boop(object):
def __init__(self, stuff):
self.stuff = stuff
def braaaap(self, green: bool, eggs = 'and ham', answer = 42):
if green:
return eggs
if answer != 42:
raise Exception # The answer is always 42.
# Too many references?
def aaa(aaaa, aaaaa = 'aaaaa'):
aaaaaa = 'aaaaaa'
return aaaaaaOutput:
stuff.txt
Docstrings for boop.py
================================================================================
line 1, boop(stuff):
"""<class description>
Initializer arguments:
stuff (<type>): <description>
Attributes:
stuff (<type>): <description>
"""
--------------------------------------------------------------------------------
line 3, boop.__init__(stuff):
"""See class docstring for details."""
--------------------------------------------------------------------------------
line 6, boop.braaaap(green, eggs, answer):
"""<function description>
Arguments:
green (bool): <description>
eggs (<type>): <description>
answer (<type>): <description>
Returns:
eggs (<type>): <description>
Raises:
Exception: <description>
"""
================================================================================
line 16, aaa(aaaa, aaaaa):
"""<function description>
Arguments:
aaaa (<type>): <description>
aaaaa (<type>): <description>
Returns:
aaaaaa (<type>): <description>
"""
--------------------------------------------------------------------------------