文档

https://farm5.staticflickr.com/4279/35620636012_f66aa88f93_k_d.jpg
可读性是Python开发者需关注的重点,这包括项目和代码文档的可读性。遵循一些简单的最佳实践能够帮助您和其他人节省很多时间。

项目文档

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

INSTALL 文件对Python来说并不必要。安装指令通常少至一条命令,比如说pip install modulepython 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 PrimerreStructuredText Quick Reference 应该会帮助您熟悉它的语法。

代码文档建议

注释能使代码清晰,将其加入到代码中是为了理解代码起来更容易。在Python中,注意以一个hash(数字符号)(“#”)开始。

在Python中, 文档字符串 用来描述模块、类和函数:

  1. def square_and_rooter(x):
  2. """返回自己乘以自己的平方根。"""
  3. ...

一般来说,要遵循 PEP 8#comments ("Python风格指南")的注释部分。更多关于文档字符串的内容可以在 PEP 0257#specification (文档字符串约定指引) 上找到。

注释代码块

不要使用三引号去注释代码。 这不是好的实践,因为面向行的命令行工具,比如说grep,不会知道注释过的代码是没有激活的。对每一个注释行,使用带有合适缩进的井号会更好。您的编辑器可能很容易做到这一点,并能切换注释/取消注释。

文档字符串和魔法

一些工具使用文档字符串来嵌入不止是文档的行为,比如说单元测试逻辑。这些可能不错,但是简单地“保持文档就是文档”您永远都不会错。

Sphinx 这样的工具会将您的文档字符串解析为reStructuredText,并以HTML格式正确呈现。这使得在示例代码片段中嵌入项目的文档非常简单。

此外, Doctest 将读取所有内嵌的看起来像Python命令行输入(以“>>>”为前缀)的文档字符串,并运行,以检查命令输出是否匹配其下行内容。这允许开发人员在源码中嵌入真实的示例和函数的用法。此外,它还能确保代码被测试和工作。

  1. def my_function(a, b):
  2. """
  3. >>> my_function(2, 3)
  4. 6
  5. >>> my_function('a', 3)
  6. 'aaa'
  7. """
  8. return a * b

文档字符串 vs 块注释

这些不可互换。对于函数或类,开头的注释区是程序员的注解。而文档字符串描述了函数或类的 操作

  1. # 由于某种原因这个函数减慢程序执行。
  2. def square_and_rooter(x):
  3. """返回自己乘以自己的平方根。"""
  4. ...

与块注释不同,文档字符串内置于Python语言本身。与被优化掉的注释相比较,这意味着您可以使用Python强大的内省功能以在运行时获得文档字符串。对于几乎每个Python对象,可以通过其 doc 属性或使用内置的“help()”函数访问文档字符串。

块注释通常用于解释一段代码是 做什么 ,或是算法的细节。而文档字符串更适合于向其他用户(或是写完代码6个月内的您)解释您代码中的特定功能是 如何 使用,或是方法、类和模块的作用。

编写文本字符串

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

  1. def addab):
  2. """两个数字相加,并返回结果。"""
  3. return a + b

文档字符串应该以易于理解的方式描述函数。对于简单的例子,如简单的函数和类,简单地将函数的签名(即add(a, b) -> result)嵌入到文档字符串中是不必要的。这是因为使用Python的“inspect”模块可以很容易地找到这些信息。此外,通过阅读源代码也可以很容易地获得。

然而,在更大或更复杂的项目中,提供相关功能的更多信息是个好主意,包括它是做什么的,所抛的任何异常,返回的内容或参数的相关细节。

对于更详细的代码文档,用于Numpy项目的风格较为流行,通常称为 Numpy style 文档字符串。虽然它之前的例子可能会占用更多的行,但它允许开发人员包含方法、函数或类的更多信息。

  1. def random_number_generatorarg1arg2):
  2. """
  3. 摘要行。
  4.  
  5. 扩展功能描述。
  6.  
  7. 参数
  8. ----------
  9. arg1:int
  10. arg1的描述
  11. arg2:str
  12. arg2的描述
  13.  
  14. 返回
  15. -------
  16. int
  17. 返回值说明
  18.  
  19. """
  20. 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