文档

../_images/35620636012_f66aa88f93_k_d.jpg

可读性是Python开发人员在项目和代码文档中的主要关注点。遵循一些简单的最佳实践可以节省您和其他人很多时间。

项目文件

A README 根目录下的文件应该向项目的用户和维护人员提供一般信息。它应该是原始文本或用一些非常容易阅读的标记编写,例如 重构文本 或者降价。它应该包含一些行来解释项目或库的目的(假设用户对项目一无所知),软件的主要源的URL,以及一些基本的信用信息。这个文件是代码阅读器的主要入口点。

INSTALL 文件对于python来说不太必要。安装说明通常简化为一个命令,例如 pip install modulepython setup.py install ,并添加到 README 文件。

A LICENSE 文件应该 总是 请出示并指定向公众提供软件的许可证。

A TODO 文件或 TODO 段在 README 应列出代码的计划开发。

A CHANGELOG 文件或节 README 应该为最新版本编译代码库中的更改的简短概述。

项目出版物

根据项目的不同,您的文档可能包含以下部分或全部组件:

  • 介绍 应该显示一个非常简短的概述,说明如何使用产品,使用一个或两个非常简单的用例。这是你项目的第三十二个投球。

  • A 教程 应该更详细地显示一些主要用例。读者将按照一个循序渐进的程序来建立一个工作原型。

  • API引用 通常由代码生成(请参见 docstrings )。它将列出所有公共可用的接口、参数和返回值。

  • 开发人员文档 是为潜在的贡献者准备的。这可以包括代码约定和项目的一般设计策略。

Sphinx

Sphinx 是目前最流行的Python文档工具。 使用它。 它转换 重构文本 将标记语言转换为一系列输出格式,包括HTML、LaTex(用于可打印的PDF版本)、手册页和纯文本。

也有 伟大的free 为您的 Sphinx 文件: Read The Docs .使用它。您可以使用提交钩子将其配置到源存储库,以便自动重建文档。

跑步时, Sphinx 将导入代码,并使用Python的内省功能提取所有函数、方法和类签名。它还将提取附带的docstring,并将其编译成结构良好且易于阅读的项目文档。

注解

斯芬克斯以其API的生成而闻名,但它也适用于一般项目文档。本指南是用 Sphinx 并且托管在 Read The Docs

重构文本

大多数python文档都是用 reStructuredText. 这就像内置了所有可选扩展的降价。

这个 reStructuredText Primer 以及 reStructuredText Quick Reference 应该有助于您熟悉它的语法。

代码文档建议

注释对代码进行了澄清,添加注释的目的是使代码更容易理解。在python中,注释以散列(数字符号)开头。 (#

在 Python 中, 文档字符串 描述模块、类和函数:

def square_and_rooter(x):
    """Return the square root of self times self."""
    ...

一般来说,遵循 PEP 8#comments (“python样式指南”)。有关docstrings的更多信息,请访问 PEP 0257#specification (docstring惯例指南)。

注释代码部分

Do not use triple-quote strings to comment code .这不是一个好的实践,因为面向行的命令行工具(如grep)不会意识到注释代码处于非活动状态。最好在适当的缩进级别为每个注释行添加哈希。您的编辑器可能能够轻松地完成此操作,并且值得学习注释/取消注释切换。

文档字符串和魔法

有些工具使用docstring嵌入的不仅仅是文档行为,例如单元测试逻辑。这些可能不错,但你永远不会错的香草“这就是它的作用。”

像这样的工具 Sphinx 将把docstrings解析为restructuredtext,并将其正确呈现为html。这使得在项目文档中嵌入示例代码片段变得非常容易。

此外, Doctest 将从python命令行(前缀为“>>>”)中读取所有看起来像输入的嵌入docstring并运行它们,检查命令的输出是否与下一行中的文本匹配。这允许开发人员在源代码旁边嵌入真正的示例和函数的用法,并且作为一个副作用,它还确保测试和工作他们的代码。

def my_function(a, b):
    """
    >>> my_function(2, 3)
    6
    >>> my_function('a', 3)
    'aaa'
    """
    return a * b

文档字符串与块注释

这些不能互换。对于函数或类,前面的注释块是程序员的注释。docstring描述了 操作 函数或类的:

# This function slows down program execution for some reason.
def square_and_rooter(x):
    """Returns the square root of self times self."""
    ...

与块注释不同,docstring内置于Python语言本身。这意味着您可以在运行时使用所有Python强大的内省功能来访问docstring,与优化后的注释相比。可以从 __doc__ 几乎每个python对象的dunder属性,以及内置的 help() 功能。

而块注释通常用于解释 what 一段代码正在执行,或者算法的细节,docstring更适合向代码的其他用户解释(或者在6个月内解释) how 可以使用一个特定的函数以及函数、类或模块的一般用途。

正在写入文档字符串

根据编写的函数、方法或类的复杂性,单行docstring可能是完全合适的。这些通常用于非常明显的情况,例如:

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

docstring应该以易于理解的方式描述函数。对于一些简单的情况,比如琐碎的函数和类,只需嵌入函数的签名(即 add(a, b) -> result )在docstring中是不必要的。这是因为使用python的 inspect 模块,如果需要的话,已经很容易找到这个信息,而且通过读取源代码也很容易获得。

然而,在更大或更复杂的项目中,最好提供更多关于函数、函数的作用、函数可能引发的任何异常、函数返回的内容或参数的相关详细信息。

对于更详细的代码文档,流行的样式是用于numpy项目的样式,通常称为 NumPy style 文档字符串。虽然它可以比前一个示例占用更多的行,但它允许开发人员包含关于方法、函数或类的更多信息。地址:

def random_number_generator(arg1, arg2):
    """
    Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    int
        Description of return value

    """
    return 42

这个 sphinx.ext.napoleon 插件允许sphinx解析这种类型的docstrings,使您可以轻松地将numpy样式的docstrings合并到项目中。

一天结束时,使用什么样式来编写docstring并不重要;它们的目的是为任何需要阅读或更改代码的人提供文档。只要它是正确的,可以理解的,并且得到了相关的点,那么它就完成了它设计要做的工作。

如需进一步阅读docstring,请随时咨询 PEP 257

其他工具

你可能在野外看到这些。使用 Sphinx .

Pycco

pycco是一个“了解编程风格的文档生成器”,是node.js的一个端口。 Docco. 它使代码成为并排的HTML代码和文档。

Ronn

Ronn构建Unix手册。它将人类可读的文本文件转换为用于终端显示的roff,也将转换为用于Web的HTML。

Epydoc

Epydoc已停产。使用 Sphinx 相反。

MkDocs

mkdocs是一个快速简单的静态站点生成器,用于构建带有标记的项目文档。