文档
可读性是 Python 开发者在项目和代码文档中的主要关注点。遵循一些简单的最佳原则可以为自己和其他人节省大量时间。
（1）项目文档
1.1 README文件
README文件应该为用户和维护人员提供项目的基本信息，并被放置于根目录。它应该由纯文本构成，或者使用一些像reStructuredText或者Markdown一样的易读的标记语言。它应该用简短的语言解释编写该项目或库的目的（假设用户完全不了解该项目），还应包含该软件的主要源码的地址，以及一些基本的信用信息。这个文件就是读者阅读代码的主要切入点。
1.2 INSTALL文件
INSTALL文件在Python项目中不是必须的。安装说明通常被简化为一个命令，例如pip install module或者python setup.py install，并添加到README文件中。
1.3 LICENSE文件
LICENSE文件是必须的，用于向公众提供软件的许可证。
1.4 TODO文件
TODO文件或者是README文件中的TODO单元可以列出项目的开发计划。
1.5 CHANGELOG文件
CHANGELOG文件或者是README文件中的CHANGELOG单元用于公开项目更新说明。
（2）项目发布
2.1 根据项目的不同，文档还可能包括以下部分或全部内容：
2.1.1 用一两个简单的示例介绍项目的用法。这是项目的30秒自述。
2.1.2 一个更详细地展示项目主要功能的教程。读者将一步步地建造一个项目原型。
2.1.3 由代码（参见docstrings）生成一个API参考，它应包括所有公开的接口、参数和返回值。
2.1.4 为潜在贡献者提供的开发者文档。它包含编码风格和设计策略。
2.2 Sphinx
Sphinx是最流行的Python文档工具。它能将reStructuredText格式的文本转换为其它格式，包括HTML、LaTeX（可打印的PDF版）、手册页和纯文本。
还有一个伟大的，免费托管Sphinx文件的工具：Read The Docs。可以通过它使用钩子来对源存储库进行配置，以便自动重建文档。
运行时，Sphinx将导入您的代码，并使用Python的内省功能提取所有函数、方法和类签名。它还将提取附带的docstring，并将其编译成结构良好、易于阅读的项目文档。
注释：Sphinx以其API生成功能而闻名，但它也适用于一般项目文档。本指南由Sphinx构建，并托管在Read The Docs上。
2.3 reStructuredText
大多数Python文档都是用reStructuredText语言编写的。它像 Markdown一样，但是内置了所有可选的扩展。
使用reStructuredText Primer和 reStructuredText Quick Reference可以熟悉其语法。
（3）代码文档建议
为使代码更易于理解，应该添加注释。在Pathon 中，注释由井号开始。
在 Python 中，docstring 描述模块、类和函数：
|
def square_and_rooter(x): '''Return the square root of self times self.''' ... |
一般来说，请遵循PEP8#comment（Python风格指南）的注释部分。有关docstring的更多信息，请参阅PEP 0257specification（Docstring风格指南）。
3.1注释代码块
不要使用三重引号来注释代码。这不是一个好习惯。因为面向行的命令行工具（如grep）无法识别多行注释。每个注释行都应选择的适当缩进级别，编辑器可以轻松地做到这些。Python使用者应当掌握利用编辑器注释代码和取消注释方法。
3.2 Docstrings和魔法
有些工具会使用docstrings来嵌入“非文档类信息”，如单元测试逻辑等。这也挺好，但在docstrings中使用文字明了地解释程序功能会更好地避免犯错。
Sphinx之类的工具将把docstrings解析为reStructuredText，并将其呈现为HTML。这使得在项目文档中嵌入示例代码片段变得非常容易。
此外，Doctest将读取所有看起来像Python命令行输入的docstrings内容（以“gt;gt;gt;”为前缀），并运行它们，检查它的输出是否与下一行的文本匹配。这使得开发人员能够在源代码中嵌入真实示例和函数用法。同时，也可以确保代码是经过测试的并能正常工作的。
|
def my_function(a, b): ''' gt;gt;gt; my_function(2, 3) 6 gt;gt;gt; my_function(a, 3) aaa ''' return a * b |
3.3 Docstrings与注释块
它们不能互换。对函数或者类来说，首部注释块是程序员的笔记，而docstrings描述了它们的功能：
|
# 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，与之相对地，注释块会被优化掉。对于几乎每个Python对象，都可以利用__doc__属性以及内置的help()函数访问docstring。
3.4 编写Docstrings
根据编写的函数、方法或类的复杂性，单行的docstring可能会很合适。通常这适用于一些简单情况，例如：
|
def add(a, b): '''Add two numbers and return the result.''' return a b ``` |
docstring应该以易于理解的方式描述函数。而对于一些非常简单的情况，没必要只是将函数的签名（即add(a，b) -gt; result）嵌入到docstring中。这是因为如果需要的话，利用Python的inspect模块，就可以很容易地找到这些信息，而且通过阅读源代码也可以很方便地理解它们。
但是，在更大或更复杂的项目中，最好提供更多有关函数的信息，比如其作用、可能引发的异常、返回值或者有关参数的细节。
对于更详细的代码文档，NumPy项目所使用的样式更加流行，通常称为NumPy风格的docstring。虽然它比前面的示例占用更多的行，但它允许开发人员添加更多关于方法、函数或类的信息。
|
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样式的docstring合并到项目中。
说到底，用什么风格来编写docstring并不重要，它的目的是为任何可能需要阅读或更改代码的人提供文档。只要它是正确的、可以理解的，并能切中要点，那么它就实现了其设计目的。
有关docstrings的进一步阅读，请随时查阅PEP 257。
（4）其它工具
4.1 Pycco
Pycco是一个“文学-编程”风格的文档生成器，是node.js Docco的移植版本。它可以并排地显示HTM代码和文档。
4.2 Ronn
Ronn用于构建Unix手册。它将人类可读的文本文件转换为roff文件用于终端显示，也能转换为用于web的HTML文件。
4.3 Epydoc
Epydoc已不再开发。可使用Sphinx。
4.4 MkDocs
MkDocs是一个快速而简单的静态站点生成器，适用于通过Markdown构建项目文档。
外文原文资料信息
[1] 外文原文作者：Orsquo;Reilly
[2] 外文原文所在书名或论文题目：The Hitchhikerrsquo;s Guide to Python
[3] 外文原文来源：
网页地址：https://docs.python-guide.org/writing/documentation/
二、外文原文资料：
Documentation
Readability is a primary focus for Python developers, in both project and code documentation. Following some
simple best practices can save both you and others a lot of time.
Project Documentation
A README file at the root directory should give general information to both users and maintainers of a project. It
should be raw text or written in some very easy to read markup, such as r
剩余内容已隐藏，支付完成后下载完整资料
英语原文共 4 页，剩余内容已隐藏，支付完成后下载完整资料
资料编号：[595974]，资料为PDF文档或Word文档，PDF文档可免费转换为Word
课题毕业论文、文献综述、任务书、外文翻译、程序设计、图纸设计等资料可联系客服协助查找。
