alphadoc
Automatic docstring generator and style guide that supports a number of specified conventions for documentation in Python.
Features
- Auto-generates docstrings with a customizable template for functions.
- Automatically fixes the code according to the standard PEP-8 style convention for python.
- Support for common and widely used docstrings formats such as Numpy, Google, ReStructured Text and Epytext (Javadoc)
Installation
Using pip:
$ pip install alphadoc
Usage
alphadoc takes your filename and format type as arguments
$ alphadoc <filename> --d <doc_format>
See alphadoc --help for more command-line switches and options!
Options :
Usage: alphadoc [OPTIONS] FILENAME
Automatic docstring generator and style guide that supports a
number of specified conventions for formatting as well as
documentation in Python.
Options:
-d, --doc_format TEXT Specified format for docstrings from Options-
ReST : For ReStructured Text (default); Epytext
: For Epytext (Javadoc); Google : For Google-
Style ; Numpydoc : For Numpydoc
--help Show this message and exit.
Example :
Before alphadoc
import ast
import sys
def top_level_functions(body):
return (f for f in body if isinstance(f, ast.FunctionDef))
def parse_ast(filename):
with open(filename, "rt") as file:
return ast.parse(file.read(), filename=filename)
def get_func(filename):
tree = parse_ast(filename)
func_list = []
for func in top_level_functions(tree.body):
func_list.append(func.name)
return func_listAfter alphadoc
Docstring format:
- ReStructured Text (default)
import ast
import sys
def top_level_functions(body):
"""
This is reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
return (f for f in body if isinstance(f, ast.FunctionDef))
def parse_ast(filename):
"""
This is reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
with open(filename, "rt") as file:
return ast.parse(file.read(), filename=filename)
def get_func(filename):
"""
This is reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
tree = parse_ast(filename)
func_list = []
for func in top_level_functions(tree.body):
func_list.append(func.name)
return func_list- Epytext (Javadoc)
import ast
import sys
def top_level_functions(body):
"""
This is javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
return (f for f in body if isinstance(f, ast.FunctionDef))
def parse_ast(filename):
"""
This is javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
with open(filename, "rt") as file:
return ast.parse(file.read(), filename=filename)
def get_func(filename):
"""
This is javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
tree = parse_ast(filename)
func_list = []
for func in top_level_functions(tree.body):
func_list.append(func.name)
return func_listimport ast
import sys
def top_level_functions(body):
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
return (f for f in body if isinstance(f, ast.FunctionDef))
def parse_ast(filename):
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
with open(filename, "rt") as file:
return ast.parse(file.read(), filename=filename)
def get_func(filename):
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
tree = parse_ast(filename)
func_list = []
for func in top_level_functions(tree.body):
func_list.append(func.name)
return func_list- Numpydoc
import ast
import sys
def top_level_functions(body):
"""
Numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
return (f for f in body if isinstance(f, ast.FunctionDef))
def parse_ast(filename):
"""
Numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
with open(filename, "rt") as file:
return ast.parse(file.read(), filename=filename)
def get_func(filename):
"""
Numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
tree = parse_ast(filename)
func_list = []
for func in top_level_functions(tree.body):
func_list.append(func.name)
return func_listReferences
http://daouzli.com/blog/docstring.html
Contributing
alphadoc is fully Open-Source and open for contributions! We request you to respect our contribution guidelines as defined in our CODE_OF_CONDUCT.md and CONTRIBUTING.md
