緣起

大部分開發人員不喜歡寫文件。但是一個合格的可維護專案，必須要有足夠的文件，因此一個專案開發到一定階段後需要適當的編寫文件。專案的型別多種多樣，有許多專案屬於內部專案，例如一個內部的開發引擎，或者一個本身就是面向開發者的專案。

本文考慮的是這種面向開發者的專案文件編寫。通過本文，你將快速獲得如下技能：

• 理解開發專案文件的基本要素
• 掌握編寫有頭有尾結構化文件的能力
• 獲得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
• 接著，執行nom install來安裝依賴的node modules。
• 接著，在doc目錄下執行命令生成文件：node doc.js docs.starlab docs.starlab.io
  • 注意docs.js的第一個引數是文件源目錄，第二個引數是我們希望生成的網站目錄
    • docs.js會自動安裝依賴的gitbook-cli，首次安裝會慢一些。
• 可以看到瀏覽器已經打開了生成的文件：

文件目錄設計

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--