Python代码的自动样式指南和docstrings生成器
alphadoc的Python项目详细描述
阿尔法多克
自动docstring生成器和样式指南，支持Python中文档的许多指定约定。在
特点
- 使用可自定义的函数模板自动生成docstring。在
- 根据python的标准PEP-8样式约定自动修复代码。在
- 支持常见和广泛使用的docstring格式，如Numpy、Google、structured Text和Epytext（Javadoc）
安装
使用pip：
$ pip install alphadoc
使用
alphadoc将文件名和格式类型作为参数
^{pr2}$有关更多命令行开关和选项，请参见alphadoc --help！在
选项：
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.
示例：
在alphadoc之前
importastimportsysdeftop_level_functions(body):return(fforfinbodyifisinstance(f,ast.FunctionDef))defparse_ast(filename):withopen(filename,"rt")asfile:returnast.parse(file.read(),filename=filename)defget_func(filename):tree=parse_ast(filename)func_list=[]forfuncintop_level_functions(tree.body):func_list.append(func.name)returnfunc_list
在alphadoc之后
Docstring格式：
- structured Text（默认）
importastimportsysdeftop_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(fforfinbodyifisinstance(f,ast.FunctionDef))defparse_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 """withopen(filename,"rt")asfile:returnast.parse(file.read(),filename=filename)defget_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=[]forfuncintop_level_functions(tree.body):func_list.append(func.name)returnfunc_list
- Epytext（Javadoc）
importastimportsysdeftop_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(fforfinbodyifisinstance(f,ast.FunctionDef))defparse_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 """withopen(filename,"rt")asfile:returnast.parse(file.read(),filename=filename)defget_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=[]forfuncintop_level_functions(tree.body):func_list.append(func.name)returnfunc_list
importastimportsysdeftop_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(fforfinbodyifisinstance(f,ast.FunctionDef))defparse_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. """withopen(filename,"rt")asfile:returnast.parse(file.read(),filename=filename)defget_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=[]forfuncintop_level_functions(tree.body):func_list.append(func.name)returnfunc_list
- Numpydoc
importastimportsysdeftop_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(fforfinbodyifisinstance(f,ast.FunctionDef))defparse_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 """withopen(filename,"rt")asfile:returnast.parse(file.read(),filename=filename)defget_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=[]forfuncintop_level_functions(tree.body):func_list.append(func.name)returnfunc_list
参考文献
http://daouzli.com/blog/docstring.html
贡献
alphadoc是完全开放的源代码和开放的贡献！我们要求您遵守我们在CODE_OF_CONDUCT.md和CONTRIBUTING.md中定义的贡献指导原则
- 项目
标签：
欢迎加入QQ群-->： 979659372
