文档

文档

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

项目文档

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

INSTALL 文件对Python来说并不必要。安装指令通常少至一条命令，比如说pip install module 或 python 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的内省功能，它将提取所有函数，方法和类签名。它还将提取附带的文档字符串，并将其全部编译成结构良好且易于阅读的文档。

注解

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

reStructuredText

大多数Python文档是用 reStructuredText 编写的。它就像是内建了所有可选扩展的Markdown。

reStructuredText Primer 和 reStructuredText 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的项目文档。

原文: http://pythonguidecn.readthedocs.io/zh/latest/writing/documentation.html