Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/v2dha/alphadoc
Automatic docstring generator that supports and generates a number of specified and widely used docstring style conventions for documentation in Python.
https://github.com/v2dha/alphadoc
docstring-generator docstrings-formats documentation-generator
Last synced: 1 day ago
JSON representation
Automatic docstring generator that supports and generates a number of specified and widely used docstring style conventions for documentation in Python.
- Host: GitHub
- URL: https://github.com/v2dha/alphadoc
- Owner: V2dha
- License: mit
- Created: 2020-11-18T20:10:23.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2021-04-15T09:49:07.000Z (almost 4 years ago)
- Last Synced: 2024-08-08T16:33:13.485Z (6 months ago)
- Topics: docstring-generator, docstrings-formats, documentation-generator
- Language: Python
- Homepage: https://pypi.org/project/alphadoc/
- Size: 4.95 MB
- Stars: 6
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# alphadoc
[](https://pypi.org/project/pdoc3)
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.
* Support for common and widely used docstrings formats such as Numpy, Google, ReStructured Text and Epytext (Javadoc)
Installation
------------
Using pip:
$ pip install alphadoc
Demo
-----
Usage
-----
alphadoc takes your filename and format type as arguments
$ alphadoc -d
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
```python
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)
```python
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)**
```python
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
```
* **Google**
```python
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**
```python
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](CODE_OF_CONDUCT.md) and [CONTRIBUTING.md](CONTRIBUTING.md)
## Contributors
