文档¶

../_images/35620636012_f66aa88f93_k_d.jpg

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

项目文件¶

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

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

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

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

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

项目出版物¶

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

一个引言应该使用一个或两个极其简化的用例，非常简短地概述产品可以做些什么。这是你的项目的第三十二次推销。
A 教程应该更详细地显示一些主要用例。读者将按照一个循序渐进的程序来建立一个工作原型。
An*API引用* 通常由代码生成（请参见 docstrings ）。它将列出所有公共可用的接口、参数和返回值。
开发人员文档 是为潜在的贡献者准备的。这可以包括代码约定和项目的一般设计策略。

Sphinx¶

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

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

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

备注

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

reStructuredText¶

大多数Python文档都是用 reStructuredText. 它类似于Markdown，但内置了所有可选的扩展。

这个 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命令行的输入的嵌入式文档字符串(前缀为“>”)并运行它们，检查命令的输出是否与下一行上的文本匹配。这允许开发人员在源代码中嵌入真实的示例和函数用法。作为一个副作用，它还确保他们的代码经过测试并正常工作。

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 正在执行的一段代码，或者算法的细节，文档字符串更多地用于解释您的代码的其他用户(或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是一个快速简单的静态站点生成器，用于构建带有标记的项目文档。

文档¶