项目文档

优质

小牛编辑

136浏览

2023-12-01

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

项目文档

在根目录下 README 文件应该对用户和项目维护者提供概述信息。它应该是原始文本或非常容易阅读的标记写成，如 reStructuredText 或 Markdown。它应该包含几行对项目或库的作用的解释（假设用户不知道项目的任何内容），软件源站点的 URL 和一些基本的信用信息。这个文件应该是代码阅读者的主要入口点。

INSTALL 文件对 Python 来说不是必需的。安装指令通常被简化为一个命令，如 pip install module 或 python setup.py install 并且添加到 README 文件中。

LICENSE 文件应该 始终 存在并且详细说明软件在什么许可证下对公众可用。

TODO 文件或 README 文件中的 TODO 部分应该列出代码的开发计划。

CHANGELOG 文件或在 README 对应的部分应该基于最新版本编写一个代码变更概述。

其他文档

根据项目的不同，文档中最好能包含下列部分或所有的内容：

一份 简短介绍 ，应该包含几个简化的用例，简要概述该产品能够用来做什么。
一份教程，应该展示一些主要的用例以及更多的使用细节。读者能够跟着一步步成功搭建工作原型。
一份 API 文档 ，通常从代码中产生（参见 docstrings）。它会列出所有的可供公共访问的接口、参数和返回值。
一份 贡献文档 适用于潜在贡献者。这可以包括项目的代码规范和通用设计的策略讲解。

Sphinx

Sphinx 无疑是最流行的 Python 文档工具。 我们推荐在项目中使用 Sphinx。 它能把 reStructuredText 标记语言转换为流行的输出格式，包括 HTML、LaTeX (可打印 PDF 版本)、手册和纯文本。

Read The Docs 是一个 超棒的 并且 免费的 文档托管平台，可以托管您的 Sphinx 文档。您可以为它配置提交钩子到您的代码库中，这样文档的重新构建即可自动进行。

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

Sphinx 因生成 API 文档而著名，但它也适用于普通的文档。本指南（译者注：原始文档）使用 Sphinx 进行构建，并托管在 Read The Docs 上。

reStructuredText

大多数 Python 文档是用 reStructuredText 编写的。它是一个内建了所有可选扩展的 Markdown 解析器。

reStructuredText Primer 和 reStructuredText Quick Reference 这两个文档应该能帮助你快速熟悉它的语法。

源码文档建议

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

在 Python 中我们使用 文档字符串（docstrings） 用来描述模块、类和函数：

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

一般来说，我们要遵循 PEP 8#comments （" Python 风格指南"）的注释部分。更多关于 docstrings 的内容可以在 PEP 0257#specification （docstrings 约定指南）上找到。

注释代码块

请不要使用三引号去注释代码。这不是好的实践，因为面向行的命令行处理工具，比如说 grep，将会很难判断注释掉的代码是否是激活的。对每一个注释行，最好使用带有合适缩进的井号。您的编辑器可能很容易做到这一点，并能使用快捷键就切换注释 / 取消注释。

Docstrings 的魔法

一些工具使用 Docstrings 来嵌入不止是文档的行为，比如说单元测试逻辑等。接下来会给你讲解 Docstrings 的一些奇特的用法，不过话说回来，如果你只是使用 Docstrings 来做函数文档也是完全合理的。

像 Sphinx 这样的工具会将 Docstrings 解析为 reStructuredText，并以 HTML 格式正确呈现。这使得将示例代码片段嵌入到项目文档成为可能。

此外， Doctest 能够读取所有内嵌的看起来像 Python 命令行输入（以 >>> 为前缀）的 Docstrings 并对其进行运行，以检查命令输出是否匹配其下行内容。这允许开发人员在源码中嵌入真实的示例和函数的用法。此外，它还能确保代码运行过测试并且正常工作。

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

Docstrings 与块注释的比较

他们俩是不可互换。对于函数或类，开头的注释区是程序员的注解。而Docstrings 描述了函数或类的 操作性文档 ：

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

块注释会在脚本执行时被优化掉，与块注释不同，Docstrings 内置于 Python 语言本身。这意味着你可以使用 Python 强大的内省功能以在运行时获得 Docstrings 。对于几乎每个 Python 对象，我们都可以通过其 **doc** 属性或使用内置的 help() 函数来访问 Docstrings。

块注释通常用于解释一段代码是 做什么 ，或是算法的细节。而 Docstrings 更适合于向其他用户（或是写完代码 6 个月以后的你）解释代码中的特定功能是 如何 使用，或是方法、类和模块的作用。

编写 Docstrings

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

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

Docstrings 应该以易于理解的方式来描述函数。另一方面，对于简单的函数和类，将函数的签名（即 add(a, b) -> result ）嵌入到 Docstrings 中是没有必要的。这是因为使用 Python 的 "inspect" 模块可以很容易地找到这些信息。此外，这些信息也可以简单地通过阅读源代码来获得。

在更大或更复杂的项目中，我们建议提供相关函数的更多信息，包括它是做什么的，所抛的任何异常，返回的内容或参数的相关细节。

对于更详细的代码文档，用于 Numpy 项目上的 Docstrings 风格会更为流行，通常称为 Numpy style Docstrings。因为可以占用更多的行，所以它允许开发人员写入更多的信息。

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

    扩展功能描述。

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

    返回
    -------
    int
        返回值说明
    """
    return 42

Sphinx 下使用 sphinx.ext.napoleon 插件即可解析这种风格的 Docstrings，使您可以轻松地将 NumPy 风格文档植入到你的项目中。

最后，编写 Docstrings 的风格并没那么重要，它们的目的是为任何可能需要阅读或更改代码的人提供文档。只要它是正确的，可以理解的，切中相关点，那么它就很完美地完成了它的使命。

要进一步阅读 Docstrings，请随时参见 PEP 257

其他工具

你可能在其他场景看到过这些，不过没有特殊情况的话，请尽量使用 Sphinx。

Pycco

Pycco是一个 "文学编程风格的文档生成器"，它是 node.js Docco 的移植版本。它将代码生成为一个并排的 HTML 代码区块和对应的文档。

Ronn

Ronn 用来构建 Unix 手册。它将人可读的文本文件转换成用于终端显示的 roff 文件, 以及用于 web 的 HTML 文件。

Epydoc

Epydoc 已经停止维护。请使用 Sphinx 来替代。

MkDocs

MkDocs 是一个快速简单的静态网站生成器，它适合于构建使用 Markdown 编写的项目文档。