Automatic style guide and docstrings generator for Python code
Project description
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_list
After 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_list
import 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_list
References
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file alphadoc-1.0.3.tar.gz
.
File metadata
- Download URL: alphadoc-1.0.3.tar.gz
- Upload date:
- Size: 5.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 60b1cce58c454b017f74fd4b3227e15cbd321d51d6c1f7fce34401b7e492ffc7 |
|
MD5 | 72f6ee475b0a3f588c48ffcaf4cda00e |
|
BLAKE2b-256 | 1394c662e76208c4cfbccc2d84af75d466c6e4cac222c589ca44cb80b22747b3 |
File details
Details for the file alphadoc-1.0.3-py3.6.egg
.
File metadata
- Download URL: alphadoc-1.0.3-py3.6.egg
- Upload date:
- Size: 11.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5380a2b703016fe3041d4c9fdd78433761053db08a5ceb5a4b324c1cff6dbe56 |
|
MD5 | aa69bc636226f42ab4dca80cb2823f8e |
|
BLAKE2b-256 | 41a97b91e5a2fecbe4879a6d32a800ee3b579eb5c12186e1d93f606a8602ade6 |
File details
Details for the file alphadoc-1.0.3-py3-none-any.whl
.
File metadata
- Download URL: alphadoc-1.0.3-py3-none-any.whl
- Upload date:
- Size: 7.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.53.0 CPython/3.6.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 32e0bb5f8daaafbf1d063db89b53994db4011ce350fa50631f74d2ce1e8fc4de |
|
MD5 | a2c721e0c897d7d3f11478f9c9481e70 |
|
BLAKE2b-256 | f8a4fb15283165c4293c1f94ac9511ab9088114e66b261c3dc10425d0a2d5720 |