文档

https://farm5.staticflickr.com/4279/35620636012_f66aa88f93_k_d.jpg

可读性是Python开发者需关注的重点,这包括项目和代码文档的可读性。遵循一些 简单的最佳实践能够帮助您和其他人节省很多时间。

项目文档

根目录下的 README 文件应该告诉用户和维护者关于项目的基本信息。它应该是 原始文本,用一些非常容易阅读的标记,比如 reStructuredText 或 Markdown。 它应该包含几行内容用来解释项目或者库的目的(假设用户不用知道任何关于该项目的事), 软件主要源的URL,以及一些基本的信用信息。此文件是代码阅读者的主要入口。

INSTALL 文件对Python来说并不必要。安装指令通常少至一条命令,比如说 pip install modulepython setup.py install ,这被添加到 README 文件中。

LICENSE 文件应该 总是 存在的,而且应该指定向公众开放的软件许可。

TODO 文件或者位于 README 中的 TODO 区域应该列出代码的开发计划。

CHANGELOG 文件或者位于 README 中的 CHANGELOG 区域应该呈现对 代码库的最新修改的简短概述。

项目发布

根据项目,您的文档中可能包含下列部分或所有的内容:

  • 一份 介绍 应该用一两个极其简化的用例,来非常简短地概述该产品 能够用来做什么。这是您的项目的30秒的自我陈述(thirty-second pitch)。
  • 一份 教程 应该展示一些主要的用例,它要有更多细节。读者将会跟着一步步搭建 工作原型。
  • 一份 API 参考 通常从代码(参见 docstrings)中产生。 它会列出所有的可供公共访问的接口、参数和返回值。
  • 开发人员文档 适用于潜在贡献者。这可以包括项目的代码惯例和通用设计策略。

Sphinx

Sphinx 无疑是最流行的Python文档工具。请使用它吧。 它能把 reStructuredText 标记语言转换为广泛的输出格式,包括HTML、LaTeX(可打印PDF版本)、手册页和纯文本。

Read The Docs 是一个 超棒的 并且 免费的 文档托管,可以托管您的 Sphinx 文档。 请使用它。您可以为它配置提交钩子到您的源库中,这样文档的重新构建将会自动进行。

运行时,Sphinx_将导入您的代码,并使用Python的内省功能,它将提取所有函数,方法和类签名。 它还将提取附带的文档字符串,并将其全部编译成结构良好且易于阅读的文档。

Note

Sphinx因API生成而著名,但它也适用于普通的项目文档。本指南使用 Sphinx 进行构建, 并托管在 Read The Docs 上。

reStructuredText

大多数Python文档是用 reStructuredText 编写的。它和Markdown类似,但内建了所有可选扩展。

reStructuredText PrimerreStructuredText Quick Reference 应该会帮助 您熟悉它的语法。

代码文档建议

注释能使代码清晰,将其加入到代码中是为了理解代码起来更容易。在Python中,注释以一个hash(数字符号)(“#”)开始。

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

def square_and_rooter(x):
    """返回自己乘以自己的平方根。"""
    ...

一般来说,要遵循 PEP 8#comments (”Python风格指南”)的注释部分。 更多关于文档字符串的内容可以在 PEP 0257#specification (文档字符串约定指引) 上找到。

注释代码块

不要使用三引号去注释代码。 这不是好的实践,因为面向行的命令行工具, 比如说grep,不会知道注释过的代码是没有激活的。对每一个注释行,使用带有 合适缩进的井号会更好。您的编辑器可能很容易做到这一点,并能切换注释/取消注释。

文档字符串和魔法

一些工具使用文档字符串来嵌入不止是文档的行为, 比如说单元测试逻辑。这些可能不错,但是简单地“保持文档就是文档”您永远都不会错。

Sphinx 这样的工具会将您的文档字符串解析为reStructuredText,并以HTML格式正确呈现。 这使得在示例代码片段中嵌入项目的文档非常简单。

此外, Doctest 将读取所有内嵌的看起来像Python命令行输入(以“>>>”为前缀)的文档字符串, 并运行,以检查命令输出是否匹配其下行内容。这允许开发人员在源码中嵌入真实的示例和函数的用法。 此外,它还能确保代码被测试和工作。

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

文档字符串 vs 块注释

这些不可互换。对于函数或类,开头的注释区是程序员的注解。而文档字符串 描述了函数或类的 操作

# 由于某种原因这个函数减慢程序执行。
def square_and_rooter(x):
    """返回自己乘以自己的平方根。"""
    ...

与块注释不同,文档字符串内置于Python语言本身。与被优化掉的注释相比较, 这意味着您可以使用Python强大的内省功能以在运行时获得文档字符串。 对于几乎每个Python对象,可以通过其 __doc__ 属性或使用内置的“help()”函数访问文档字符串。

块注释通常用于解释一段代码是 做什么 ,或是算法的细节。而文档字符串 更适合于向其他用户(或是写完代码6个月内的您)解释您代码中的特定功能是 如何 使用, 或是方法、类和模块的作用。

编写文档字符串

取决于函数、方法或类的复杂度,使用单行文档字符串可能十分合适。 以下通常用于非常明显的情况,例如:

def add(a,b):
    """两个数字相加,并返回结果。"""
    return a + b

文档字符串应该以易于理解的方式描述函数。对于简单的例子,如简单的函数和类, 简单地将函数的签名(即`add(a, b) -> result`)嵌入到文档字符串中是不必要的。 这是因为使用Python的“inspect”模块可以很容易地找到这些信息。 此外,通过阅读源代码也可以很容易地获得。

然而,在更大或更复杂的项目中,提供相关功能的更多信息是个好主意,包括它是做什么的, 所抛的任何异常,返回的内容或参数的相关细节。

对于更详细的代码文档,用于Numpy项目的风格较为流行,通常称为 Numpy style 文档字符串。 虽然它之前的例子可能会占用更多的行,但它允许开发人员包含方法、函数或类的更多信息。

def random_number_generator(arg1,arg2):
    """
    摘要行。

    扩展功能描述。

    参数
    ----------
    arg1:int
        arg1的描述
    arg2:str
        arg2的描述

    返回
    -------
    int
        返回值说明

    """
    return 42

sphinx.ext.napoleon 插件可以让Sphinx解析这种风格的文档字符串, 使您可以轻松地将NumPy风格的文档输入到项目中。

最后,编写文档字符串的风格并没那么重要,它们的目的是为任何可能需要阅读或更改代码的人提供文档。 只要它是正确的,可以理解的,切中相关点,那么它就完成了所设计的工作。

要进一步阅读docstrings,请随时参见 PEP 257

其他工具

您可能在其他场景看到过这些。使用 Sphinx

Pycco
Pycco是一个 “文学编程风格的文档生成器”,它是node.js Docco 的 移植版本。它将代码生成为一个并排的HTML代码和文档。
Ronn
Ronn用来构建Unix手册。它将人可读的文本文件转换成用于终端显示的roff文件, 以及用于web的HTML文件。
Epydoc
Epydoc已经中断开发。使用 Sphinx 来替代。
MkDocs
MkDocs是一个快速简单的静态网站生成器,它适合于构建使用Markdown的项目文档。