5.4. 项目文档 | 写出优雅的 python 代码 |《python 最佳实践指南 2018 2018》| python 技术论坛-金年会app官方网
可读性是 python 开发人员在项目和代码文档中的主要关注点。遵循一些简单的最佳实践可以为您和其他人节省大量时间。
项目文档
在根目录下 readme 文件应该对用户和项目维护者提供概述信息。它应该是原始文本或非常容易阅读的标记写成，如 或 markdown。 它应该包含几行对项目或库的作用的解释（假设用户不知道项目的任何内容），软件源站点的 url 和一些基本的信用信息。这个文件应该是代码阅读者的主要入口点。
install 文件对 python 来说不是必需的。安装指令通常被简化为一个命令，如 pip install module 或 python setup.py install 并且添加到 readme 文件中。
license 文件应该 始终 存在并且详细说明软件在什么许可证下对公众可用。
todo 文件或 readme 文件中的 todo 部分应该列出代码的开发计划。
changelog 文件或在 readme 对应的部分应该基于最新版本编写一个代码变更概述。
其他文档
根据项目的不同，文档中最好能包含下列部分或所有的内容：
- 一份 简短介绍 ，应该包含几个简化的用例，简要概述该产品能够用来做什么。
- 一份 教程 ，应该展示一些主要的用例以及更多的使用细节。读者能够跟着一步步成功搭建工作原型。
- 一份 api 文档，通常从代码中产生（参见 ）。它会列出所有的可供公共访问的接口、参数和返回值。
- 一份 贡献文档 适用于潜在贡献者。这可以包括项目的代码规范和通用设计的策略讲解。
sphinx
无疑是最流行的 python 文档工具。我们推荐在项目中使用 sphinx。 它能把 标记语言转换为流行的输出格式，包括 html、latex (可打印 pdf 版本)、手册和纯文本。
是一个 超棒的 并且 免费的 文档托管平台，可以托管您的 文档。您可以为它配置提交钩子到您的代码库中，这样文档的重新构建即可自动进行。
运行 时首先导入你的代码，它会使用 python 的内省功能来提取所有函数，方法和类签名，同时提取附带的文档字符串，并将其全部编译成结构良好且易于阅读的文档。
sphinx 因生成 api 文档而著名，但它也适用于普通的文档。本指南（译者注：原始文档）使用 进行构建， 并托管在 上。
restructuredtext
大多数 python 文档是用 编写的。它是一个内建了所有可选扩展的 markdown 解析器。
和 这两个文档应该能帮助你快速熟悉它的语法。
源码文档建议
注释能使代码清晰，将其加入到代码中是为了理解代码起来更容易。注释在 python 中以一个 hash 开始（数字符号）（"#"）。
在 python 中我们使用 文档字符串（docstrings） 用来描述模块、类和函数：
def square_and_rooter(x):
"""return the square root of self times self."""
...
一般来说，我们要遵循 （" python 风格指南"）的注释部分。 更多关于 docstrings 的内容可以在 （docstrings 约定指南） 上找到。
注释代码块
请不要使用三引号去注释代码。 这不是好的实践，因为面向行的命令行处理工具， 比如说 grep，将会很难判断注释掉的代码是否是激活的。对每一个注释行，最好使用带有合适缩进的井号。您的编辑器可能很容易做到这一点，并能使用快捷键就切换 注释 / 取消注释。
docstrings 的魔法
一些工具使用 docstrings 来嵌入不止是文档的行为， 比如说单元测试逻辑等。接下来会给你讲解 docstrings 的一些奇特的用法，不过话说回来，如果你只是使用 docstrings 来做函数文档也是完全合理的。
像 这样的工具会将 docstrings 解析为 restructuredtext，并以 html 格式正确呈现。 这使得将示例代码片段嵌入到项目文档成为可能。
此外， 能够读取所有内嵌的看起来像 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 bdocstrings 应该以易于理解的方式来描述函数。另一方面，对于简单的函数和类， 将函数的签名（即 add(a, b) -> result ）嵌入到 docstrings 中是没有必要的。这是因为使用 python 的 "inspect" 模块可以很容易地找到这些信息。 此外，这些信息也可以简单地通过阅读源代码来获得。
在更大或更复杂的项目中，我们建议提供相关函数的更多信息，包括它是做什么的， 所抛的任何异常，返回的内容或参数的相关细节。
对于更详细的代码文档，用于 numpy 项目上的 docstrings 风格会更为流行，通常称为 docstrings。因为可以占用更多的行，所以它允许开发人员写入更多的信息。
def random_number_generator(arg1, arg2):
"""
摘要行。
扩展功能描述。
参数
----------
arg1：int
arg1的描述
arg2：str
arg2的描述
返回
-------
int
返回值说明
"""
return 42
sphinx 下使用 插件即可解析这种风格的 docstrings， 使您可以轻松地将 numpy 风格文档植入到你的项目中。
最后，编写 docstrings 的风格并没那么重要，它们的目的是为任何可能需要阅读或更改代码的人提供文档。 只要它是正确的，可以理解的，切中相关点，那么它就很完美地完成了它的使命。
要进一步阅读 docstrings，请随时参见
其他工具
你可能在其他场景看到过这些，不过没有特殊情况的话，请尽量使用 。
pycco是一个 "文学编程风格的文档生成器"，它是 node.js 的移植版本。它将代码生成为一个并排的 html 代码区块和对应的文档。
ronn 用来构建 unix 手册。它将人可读的文本文件转换成用于终端显示的 roff 文件, 以及用于 web 的 html 文件。
epydoc 已经停止维护。请使用 来替代。
mkdocs 是一个快速简单的静态网站生成器，它适合于构建使用 markdown 编写的项目文档。
本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 cc 协议，如果我们的工作有侵犯到您的权益，请及时联系金年会app官方网。
