文档¶
可读性是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的内省功能，它将提取所有函数，方法和类签名。 它还将提取附带的文档字符串，并将其全部编译成结构良好且易于阅读的文档。
Note
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
