工具(5): 极简开发文档编写（How-to）

缘起

一个合格的可维护项目，必须要有足够的文档，因此一个项目开发到一定阶段后需要适当的编写文档。项目的类型多种多样，有许多项目属于内部项目，例如一个内部的开发引擎，或者一个本身就是面向开发者的项目。

本文考虑的是这种面向开发者的项目文档编写。通过本文，你将快速获得如下技能：

理解开发项目文档的基本要素
掌握编写有头有尾结构化文档的能力
获得1个开发项目文档编写的模版项目和现成工具

感受

在开始之前，我们先通过几个现成的例子，直观的感受一个面向开发者的项目，其专业的文档应该是什么样的。我们通过直接截图的方式直接了当的表达这点。

Rust编程语言文档

文档地址：doc.rust-lang.org-2018

截图：

Julia编程语言文档

文档地址：docs.julialang.org-en-v1

截图：

BuckyCloud开发文档

文档地址：docs.buckycloud.com-zh-cn

截图：

小结一下，开发项目文档一般都具有如下章节：

介绍(Introduction)
快速开始(QuickStart, Helloworld, Getting Started...)
整体介绍(Common/Core/Basic Concept, Architecture, Understanding...)
开发手册(References)
示例(Examples)
知识库文章(Articles)

根据项目特点，不同类型的项目会做对应的取舍和顺序调整。

工具

工欲善其事，必先利其器。作为极简系列，我们直接了当的介绍我们的工具：

Gitbook

通过Gitbook可以在线编写文档，按照上一节的套路即可编写出相对专业的文档。但是Gitbook同时提供了一个命令行工具，使得我们可以直接在本地编写MarkDown文档，然后使用命令行工具把MarkDown转成文档网页。

Gitbook命令行工具如下，该工具基于nodejs编写，因此你需要安装nodejs：

gitbook-cli

因此你只需：

创建一个git仓库
创建完整的文档目录结构，并使用MarkDown编写章节内容
编写脚本调用gitbook-cli转换文档目录为网页
部署网页到线上即可，例如docs.example.com

快速体验

现在，我们可以通过几个命令来快速体验一下。

首先，请安装nodejs：http://nodejs.org/
其次，请克隆示例项目：git clone https://github.com/fanfeilong/doc.git
接着，执行npm install来安装依赖的node modules。
接着，在doc目录下执行命令生成文档：node doc.js docs.starlab docs.starlab.io
- 注意docs.js的第一个参数是文档源目录，第二个参数是我们希望生成的网站目录
  - docs.js会自动安装依赖的gitbook-cli，首次安装会慢一些。
可以看到浏览器已经打开了生成的文档：

如果你直接在Chrome浏览器里打开生成的静态HTML里的index.html会出现跨域请求问题，本地起网页调试的方式如下：

cd docs.starlab
gitbook serve
浏览器访问：http://localhost:4000

文档目录设计

gitbook要求根目录下必须有如下三个MarkDown文档：

index.md
README.md
SUMMARY.md

示例中，我们虚拟了一个开发项目的文档目录docs.starlab，设计目录结构如下：

.

├── 1.QuickStart

│   ├── 1.1.InstallStarlabSDK.md

│   ├── 1.2.Hello,Starlab.md

│   ├── 1.3.UnderstandingStarlabApp.md

│   ├── 1.4.HowToDebugStarlab.md

│   └── 1.5.UnderstandingDebugger.md

├── 2.LearnStarlabSDK

│   ├── 2.1.IntrudoctionToStarlab.md

│   └── 2.2.CoreConcept.md

├── 3.Examples

│   ├── 3.1.CreateEarth.md

│   ├── 3.2.CreateMars.md

│   └── 3.3.CreateMoon.md

├── 4.References

│   ├── ref_fixedstar.md

│   ├── ref_meteor.md

│   ├── ref_planet.md

│   ├── tool_fixedstar.md

│   ├── tool_meteor.md

│   └── tool_planet.md

├── README.md

├── SUMMARY.md

└── index.md

其中，index.md用来生成Introduction一节
其中，README.md是gitbook需要的，一般我们让README.md和index.md的内容一样即可。
其中，SUMMARY.md通过MarkDown来组织网页左侧的目录结构。

可以看一下SUMMARY.md的内容：

# Document

* [1. QuickStart](1.QuickStart/1.1.InstallStarlabSDK.md)

    * [1.1. Install StarlabSDK](1.QuickStart/1.1.InstallStarlabSDK.md)

    * [1.2. Hello, Starlab](1.QuickStart/1.2.Hello,Starlab.md)

    * [1.3. Understanding Starlab App](1.QuickStart/1.3.UnderstandingStarlabApp.md)

    * [1.4. How to Debug Starlab](1.QuickStart/1.4.HowToDebugStarlab.md)

    * [1.5. Understanding Debugger](1.QuickStart/1.5.UnderstandingDebugger.md)

* [2. Learn Starlab SDK](2.LearnStarlabSDK/2.1.IntrudoctionToStarlab.md)

    * [2.1. Introduction to Starlab](2.LearnStarlabSDK/2.1.IntrudoctionToStarlab.md)

    * [2.2. Core Concept](2.LearnStarlabSDK/2.2.CoreConcept.md)

* [3. Examples](3.Examples/3.1.CreateEarth.md)

    * [3.1. Create Earth](3.Examples/3.1.CreateEarth.md)

    * [3.2. Create Mars](3.Examples/3.2.CreateMars.md)

    * [3.3. Create Moon](3.Examples/3.3.CreateMoon.md)

* [4. References](4.References/ref_fixedstar.md)

    * [fixedstar](4.References/ref_fixedstar.md)

    * [meteor](4.References/ref_meteor.md)

    * [planet](4.References/ref_planet.md)

    * [fixedstar tool](4.References/tool_fixedstar.md)

    * [meteor tool](4.References/tool_meteor.md)

    * [planet tool](4.References/tool_planet.md)

注意：目录名和文档名不能含有空格，但是在SUMMARY.md里组织的时候，[text](relativepath)格式里的text可以起更友好的名字。

部署

如果需要部署，只需要把生成的网站部署到自己的网站服务器上即可。

你的尝试

相信，通过本文的方式，你可以为自己的项目快速构建内部或外部文档，如果你想了解doc.js做了什么，你可以直接阅读这个简短的工具脚本，按需定制。我用这个方式已经为好多个项目写了专业的文档，希望你也可以！GoodLuck！

--end--