教你写出一流的python 文档
1.为什么需要写文档
首先，代码是最有意义的文档，所有对于代码描述的文档主要是给：
-
不了解代码
-
没有时间阅读代码（源码太复杂）
-
不想要阅读源码
-
没有权限阅读源码
So don’t write clever code, write elegant code.
Code is more often read than written
当写code时，主要有两个观众，用户和开发者。所有的观众都同等重要，想象一下你的用户或者其他开发者正在经历和你使用其他开发者代码的痛苦。
2.注释和文档的区别 Commenting 和documenting code
在介绍写文档之前，我们先区分一下文档和注释。
通常，注释主要用于描述code for developers。 主要的观众是代码的开发者和维护者，comments 帮助读者更好的了解代码的目的和设计。
2.1基本的注释：
2.1.1 注释的主要功能
（#）🇬🇧用于简单的声明和注释，一般不超过几句
-
计划和检查：当计划在某个位置写代码时，可以先用注释声明代码区域和要实现的功能和outlining， 记得当代码写好之后，将这些注释删除。
-
代码描述： 解释特定的代码部分
-
算法描述：当使用了算法，特别是复杂的算法，解释算法如何工作和如何在你的代码中应用十分重要，如果可能，解释下为何要用算法工作。
-
tagging :描述已经知道的问题或待提高的部分 如bug fixme, todo 等
2.1.2 注释的注意事项
代码注释应该简单和专注，应避免使用长的注释。
-
使注释尽可能的接近代码，注释离代码太远容易让人迷惑
-
不要使用复杂的format 如 table ，这会导致难以维护
-
不要包括冗余的信息
-
为注释设计你的代码，设计出 easy understand concept， 读者将会很快了解你的目的，记住代码的注释是为其他读者写的，引导他们了解代码的目的。
Commenting code via type hinting ，在 python 3.5 以上可以使用type hinting来为代码写一些注释，包括输入输出的数据类型。
2.2 文档
2.2.1 Docstrings基本描述 ：
-
Docstrings，
可以帮助使用者和自己快速了解项目，python 使用内置的funtion help来打印出 objects的doctoring to the console。也可以使用
.__doc__来查看class的注释 -
docstring types:
docstring 具体的要求在pep 257中描述，主要目的是提供对object的简单描述，应该简洁高效易维护，容易让新的读者了解object的目的和使用方法。在所有情况下docstrings 应该使用(""") 来书写。通常可以被放在一行或多行。当有一行时，应该是一个quick summary。 当有多行时，则应该包括如下部分。
（1）一行summary
（2）一行空行
（3）Further elaboration
（4）空行
-
docstring 形式
docstring可以被分为3类，分别是class docstrings, package and module docstring 和 script docstrings.
(1) class docstrings :class and class method
(2) package and module docstring: package modules, functions
(3) Script docstrings:script and functions
2.2.2 docstring 详细介绍
2.2.2.1 Class:
主要用于class和class方法。在class名称下使用。
class docstrings 应该包含如下内容：
(1) 目的和作用的简介
(2) public 方法的简单描述
(3) 类属性
(4) 任何相关的子类
Class method 的docstring应该包含：
(1) 简单介绍方法是什么用来做什么
(2) 参数
(3) 有默认值或者可选的参数
(4) 执行这个方法的副作用
(5) exception
(6)使用限制
2.2.2.2 Package and module docstrings:
Module docstrings:
(1) 简单描述模块和目的
(2) 任何class, exception,functions,other objects exported
Module function docstring:
和class method 类似
2.2.2.3 stript docstrings:
script通常是单一的可执行文件，script docstrings 通常在文件的最上方，并且应该告诉用户如何使用这个脚本，通常应该使用 -h 可以打出需要的信息，如果使用argparse，英国对每个参数进行描述，command-line parsing libraries 包含更多的细节。
最后，任何自定义的活第三方的imports 应该在docstring中 允许用户知道哪些包是需要用到的。
可以参考numpy 或 scipy的docstings.
3. 为python projects 写文档
在写python projects 的文档时，要时刻记得谁是你的用户，并且来满足他们的需求，根据项目类型，一些特定的文档是需要的。
通用的项目和他的文档应该是如下格式:
项目应该包括三个主要类型：paivate, shared public, open source.
3.1 私有 project
Readme : 简单介绍项目和目的，包括requirements
Example.py : 使用project的例子
3.2 Shared 项目
共享项目是和其他人共享，文档应该要求更加严格，主要是帮助新的成员来这个项目或者为项目添加新东西。
Readme : 除了简单的介绍和requirements, 还应该包括一些先前的主要版本信息。
Example.py : 使用样例。
How to contribute : 介绍新的贡献者如何加入到这个项目中。
3.3 Public 项目：
Readme ： 简单介绍项目和其目的，包括任何特殊的依赖包或环境。另外，添加上个版本到这个版本的主要变更，另外，添加练到到未来的文档，bug 报告和其他关于这个项目的重要信息，
How to contribute : 包括新的贡献者如何对此项目作出贡献。包括发展新的功能，修复已有的问题，增加文档，新的新的测试，报告问题。
Code of conduct : 定义其他的贡献者在开发或使用你的软件时应该如何互相对待。
license
Docs :一个文件夹包含未来的的文档。主要包括4个部分，分别是教程，使用案例，参考文件和解释。
4. 如何写docs
4.1 如何写一个完整的docs
一个完整的docs应该包括以下几个部分：
(1) 教程
-
Learning -oriented 学习引导的
-
quick start 告诉新人如何快速开始
-
a lesson 是一个课程
(2) 操作指南
-
目标导向的
-
展示如何解决实际问题
-
一系列的步骤
(3) 解释
-
理解优先
-
解释性
-
提供背景和具体内容
(4) 参考文献
-
information 导向
-
描述机制
-
精确完整
详细的内容可以阅读参考文献[3]
4.2 如何写出优秀的docs
-
结构简单清晰；
所谓结构清晰就是用户能马上找到自己要查找的知识点在哪，分类清晰。有些文档爱用模棱两个的词，比如“1. 常见问题”，“2. 热点问题”,”3. 高频问题”。我有十万火急的事情，你来告诉我我到底是要先看哪个？
-
循序渐进
先从最简单的开始，然后慢慢深入。比如我们学习Java，一开始Hello World都还没跑起来就先说配置文件要怎么写，Java一大堆的xml配置文件老司机都看的眼花缭乱更别说新手，这种文档让人直接从想了解到放弃。
-
引人入胜
把能吸引人的地方展示出来，比如Unity 3D默认就带一个设计精良的游戏Demo，一看到就有学习的兴趣。另外提供的API应该直接能在浏览器里模拟出一个可调用的Demo，而不是开放的API文档需要不停的尝试，不停的踩坑才能调通。
-
文档close to code and api 方便最终使用
-
使文档avaiable to others 通过ticketing system ，版本控制，
4.3 常见的documentation工具
Sphinx,epydoc, read the docs, doxygen, mkdocs, pycoo.
5.从哪里开始写文档
-
没有文档
-
有一些文档
-
有完整的文档
-
好的文档
-
完美的文档
如果你不知道如何开始写，看看你在哪个位置，努力提高自己的文档水平。
最后，不要害怕写文档，一旦你开始写了，很容易保持下去。
Reference :
[1] https://blog.it2048.cn/article-doc-write/
[2] https://blog.jooq.org/2013/02/26/the-golden-rules-of-code-documentation/
网友评论