开发文档你用过多少，做开发必备的API开发文档平台汇总

序言

由于最近都在忙着写技术文档，所以准备总结一下我所使用的工具、以及所遇到的坑们，包括工具的选择和优缺点之类的个人感觉。

工具清单与简单描述

1. Atom ： 开源的文本编辑器，对markdown和文档管理器的支持不错，所以选择了它（还用过Sublime但个人感觉没有Atom好用）
2. github： 这个估计也不用讲了，网上的教程真是如繁星一般地多，真正使用起来很快就会熟悉基本操作
3. Mkdocs：一个markdown的文档生成工具（说是生成，但肯定不可能说是帮你写文档的，准确点说应该是帮你将多个md文件整理并且按照一定预设的theme进行部署一整套的html并且便于部署到github.io上），功能较为简单
4. Readthedocs：一个文档托管的平台
5. Sphinx：一个python的文档生成工具（大部分基于reStrcucturedText，但是Markdown也勉强可以），功能强大，灵活性高，也是readthedocs首选使用的工具。

开始写文档

Mkdocs 是我选择的第一个写文档的工具，正如它官网所介绍的那样，的确是十分方便和轻量级的工具。

使用pip进行安装了mkdocs之后，仅仅需要使用mkdocs new project_name 就可以建立起基本的一个文档的配置目录。
其中包括一个文件夹docs和最为重要的配置文件mkdocs.yml，之后也就是使用markdown先将index.md进行修改并写成一个文档的首页。

如果除了首页以外已经没有什么需要再写的话，使用mkdocs serve就可以在本地使用flask部署一个简单的网页，可以将刚刚写的那些markdown的正确的翻译成为一个网页中的效果。

除此之外，如果需要进行迁移，仅需要使用mkdocs build即可以生成连同今天html和静态资源等的一个完整的部署用文件夹。

所以总的来说，这是一个十分方便的写文档的工具。其中提供的主题也比较多，我使用的是readthedocs的主题。

但是话又说回来，由于过于方便，所以对于整个文档的配置是十分的少的。除非你自己定制化一个主题文件，包括左侧目录栏都有可能不符合你的想法。而且markdown自身也是一个相对简单的文档语言，所以能够实现的功能是真的很少。

 

readthedoc主题

就拿一个很简单的要求来说，修改显示图片的大小、对齐方式，markdown+mkdocs是实现不了的，你只能对生成的html进行后期的修改，但是这样的操作无疑是十分耗费时间以及效率低下的。

所以后面为了实现autodoc的功能，这也是个十分重要的功能。在众多的工具文档中，其中一个十分重要的自然是API，而API其实是由文档工具自动生成的，而不是自己在写文档时辛苦的再次排版一次。所以说为了实现这个API的显示功能，我们也就马上投身了sphinx的怀抱。

关于部署

在投身到sphinx之前，需要讲讲这个文档的部署的问题。这个方面其实并没有尝试太多的方案，我们直接是选择了readthedocs这个老牌的文档托管加发布网站，而值得庆幸的是，mkdoc跟sphinx其实都是readthedocs所支持的软件。所以说mkdoc也进一步被证明了其的市场地位，虽然有些缺点，但是轻量级也是很多人选择的理由。

从mkdoc投身到sphinx

其实在投身sphinx时，文档已经写的差不多了。一边写文档一边找文档编辑工具的操作似乎有点奇怪，但是问题是在于文档的文字与结构都要重新被审查敲定，所以也就多出了不少的时间在意一下这个主题跟工具的问题。

Sphinx作为一个十分老牌的一个文档编辑工具，quickstart的部分也不会过于繁杂。

同样地在使用pip install -U Sphinx安装完后，直接在命令行中使用sphinx-quickstart就可以开始初始化一个空的文档结构。
但是由于这个软件的定制化能力很强，所以其中需要回答的问题就十分之多，大多都是需要如何部署、或者需不需要某些插件之类的。虽然复杂，但也不会花很多时间。

直接就可以进入写文档的操作。

但是这个时候问题就来了。 Sphinx所接受的语言主要是rst（reStructuredText），是一门虽然与markdown相似但是定制化能力更为强的文档语言，而且由于其基于python的缘故，很多语法是十分地注重空格与缩进的。

例如在markdown中所使用的代码块的格式化符号，6个反引号，这种语法就类似于C中的大括号，是将括号内的全部内容直接识别为需要处理的变量。而在rst中，所使用的则是

.. code-block:: python

import pandas as pd
a = pd.DataFrame(data)

以上这样子，在.. code-bloc:: python后需要空一行，并且在第三行开始需要有至少1个缩进，才能正确的识别到那一部分是输入的代码。

所以说sphinx的语法对于用惯了markdown的人来说，是一个新的体验，虽然也有反引号的语法，但是却不一样了。例如说inline的code，rst也是用反引号，不过是左右各两个反引号。

关于rst的语法，sphinx也进行了十分详细的描述，其实也包括了如何通过Python定制化一个自定义的module或者function从而通过rst的语法进行使用。因为像是以上的code-block其实都是一个定制好的python module，然后通过rst进行调用了。

这么说来，rst比markdown定制化能力真的不是好了一点半点。

当然sphinx有个不好的地方，是不会自动检测代码的改动从而刷新编译好的静态网页，由于mkdocs是一个部署好的server，所以会自动检测代码改动从而刷新页面。但是sphinx似乎不存在这么个server，而是通过sphinx-build 或者说make html直接生成了静态的html资源文件夹，只能通过人为的去部署server和build了。

在艰难的写完文档以后，我们也就可以再一次开始处理readthedocs的事情了。

再次讨论部署的事情，处理readthedocs

在注册完readthedocs后，进入管理面板后是长这样的。

dashboard

 

什么项目都没有的页面，因为我是用github的账号直接登录的，当时我的第一反应是为什么看不到我github的仓库，直接选中我的仓库选择导入不是更为方便的一件事情吗。

选择import a project后，就可以看到自己当前的项目以及刚刚我说到的选择自己github项目的位置了。

import a project

(内心叨叨：好吧，上面涂划掉自己的github名字并没有啥意义了，后面我也懒得涂划掉了)，以上图片中只要点击一下，就可以看到跟这个账号所绑定的所有的仓库，选择其中之一自然可以作为一个代码库进行导入。

导入一个仓库后，我们可以直接跳到构建这一步，前面关于导入的设置什么的，因为后面都还可以改，所以就不管了。唯一一个不可改的是域名，因为readthedocs的域名是按照 文档名.readthedocs.io进行命名的，后面是不可以改的，即使你改了文档名也是不会改变域名的，这一点readthedocs官方文档也有提到。

构建

 

readthedocs的本质有些人似乎不是很清楚，我们可以通过构建这一步讲清楚readthedocs到底帮我们做了些什么，文档build后存在了哪里，为什么要构建之类的问题。

构建的详细过程日志

从上面可以看出，readthedocs其实是在它自己的服务器上，将你指定的github目录下载下来后，建立一个虚拟环境，然后再在虚拟环境下进行build html，然后再将这个目录下的html发布到github.io 上。

所以上面提到的问题都可以得到回答。本地是看不到编译后的html的，当然也无法修改。

由于这其中涉及一个虚拟环境的问题，所以readthedocs为了某些需要安装特定包（例如自己的另一个github地址的软件）的用户提供了一个选项。允许使用自定义的requirements。

以上关于如何使用自定义的requirements和怎么将github的地址放在requirements中的方法也就不谈了。。。因为真的很简单。谷歌一下就出来了。

关于autocode

使用sphinx的理由我前面已经说了，因为要写API的部分。
这里有一点要强调的是。。。使用autocode的前提是，你在代码里都把各个class 或者function的注释都写好了，这样子autocode才能按照正确的格式读取。。例如

API举栗

酱紫的一个API注释，在代码的注释中就得写成

 

代码注释长这样

---

所以说，写好一个注释也是很花时间的。。。但是最后的最后还是
希望大家都可以乐于写文档。。方便你我他。尤其是我们这种脱离大大和谷歌就活不下去的死鱼。。。

 

作者：栽生物坑里的信息汪
链接：https://www.jianshu.com/p/0aa0248767df
來源：简书
简书著作权归作者所有，任何形式的转载都请联系作者获得授权并注明出处。