工具(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--