用于从numpystyle docstrings自动生成降价文档的脚本。

npdoc2md的Python项目详细描述


npdoc2md公司

一个简单的python实用程序,用于自动将numpy样式的python docstrings转换为 与mkdocs一起使用的降价,一次一个完整的包。它还包括第二个实用程序code2npdoc,它将尝试为整个项目生成给定代码的docstring模板。在

安装

安装npdoc2md的首选方法是使用pip。(Python 3.5+必需)

pip install npdoc2md

如果pip默认为Python2,则使用pip3。您也可以从源安装:

^{pr2}$

用法

下面是使用-h标志运行npdoc2md的结果:

usage: npdoc2md [-h] [-v] -i INPUT -o OUTPUT [-s SKIP [SKIP ...]] [-d]

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Use this flag to print out npdoc2md version info.
  -i INPUT, --input INPUT
                        The path to the target python project or file to
                        convert.
  -o OUTPUT, --output OUTPUT
                        The output directory where the markdown files should
                        be placed.
  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                        List of filenames/directories to skip.
  -d, --debug           Add this flag to print detailed log messages during
                        conversion.

基本用法至少需要有效的目标和输出位置。在

npdoc2md -i C:\Users\jwlodek\demo -o C:\Users\jwlodek\demo_output

您还可以指定使用-d启用调试打印,并使用-s跳过文件,后跟一个文件列表。例如,要自动生成py_cui文档,请运行以下命令:

npdoc2md -i ..\..\..\py_cui -o ..\..\DocstringGenerated -s statusbar.py errors.py

它将忽略statusbar.pyerrors.py文件。在

npdoc2md脚本将递归地搜索目标(如果它是一个文件夹)以.py扩展名结尾的文件, 并将为“忽略”部分中未指定的每个文件生成一个降价文件。任何遇到的__init__.py文件都将使用其包含文件夹的名称作为输出标记文件的名称。在

文档规则

要使用npdoc2md,必须遵循严格的docstring样式规则:

  • 函数docstring的每一类都必须以"""开头和结尾,并且初始描述必须紧跟在"""之后。例如:"""Hello this is a function
  • AttributesParametersReturnsRaises列表使用numpy样式指导原则
  • Returns列表应该给出返回值的名称和类型以及doc消息。否则,将为返回变量指定一个泛型名称

示例

如前所述,py_cui使用npdoc2md自动生成与mkdocs一起使用的文档。 您还可以在此存储库中看到Npdoc2md.md文件,该文件是通过在其自身上运行此脚本生成的:

npdoc2md -i .\npdoc2md.py -o .\example\.

生成模板文档

写出一个项目的所有docstring是一个漫长的过程,因此编写了第二个helper脚本来帮助生成模板np文档。它有以下用途:

usage: code2npdoc [-h] [-v] -i INPUT [-c] [-s SKIP [SKIP ...]] [-d]

A utility for auto-creating base numpy style docstrings for an entire python
project.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Add this flag for displaying version information.
  -i INPUT, --input INPUT
                        Path to target python project or file
  -c, --createtemp      If this flag is set, code2npdoc will create a
                        temporary conversion folder without overriding your
                        sources.
  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                        List of filenames/directories to skip.
  -d, --debug           Add this flag to print detailed log messages during
                        conversion.

使用与基npdoc2md脚本类似的标志。如果不希望自动覆盖原始文件,请添加-c标志。在npdoc2md文件上运行此脚本的示例如下:

code2npdoc -i npdoc2md.py -c

许可证

MIT许可证
版权所有(c)2020,Jakub Wlodek

欢迎加入QQ群-->: 979659372 Python中文网_新手群

推荐PyPI第三方库


热门话题
java比较空对象   JavasocketUDP循环   更改活动时使用java“安卓.view.InflateException:二进制XM文件行”   java可以在EclipseRCP中定义ViewPart或Workbench的最小大小吗?   java试图根据用户输入对列表中的整数进行排序   java如何避免Hibernate在oneToMany关系上创建外键限制   java创建一个简单的字符串解析器,交互式外壳式   java如何解析JSON并将其值转换为数组?   JavaAzure:Image Magick提供0 KB的输出?   使用Azure Event Hubs for Apache Kafka生态系统和OAuth在Java中发送和接收消息   java如何将Oracle的Interval数据类型格式化为HH:MM格式?   java jsoup无法在安卓上正确解析HTML   java如何计算2ndArray中的距离?   java Swing Worker线程说在超类中没有Process()方法   带有内部组件的java单击JPanel   javajsp中的html引号转义   java Maven在打包jar时无法检索buildNumber   Java中的linux八进制转义导致错误的字节值,编码问题?