工具(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会出现跨域请求问题，本地起网页调试的方式如下：

1. cd docs.starlab
2. gitbook serve
3. 浏览器访问：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--