github 之 如何在項目中加入專業的文檔說明

入門教程

http://www.liaoxuefeng.com/

前言

    我們在github中常見一些項目有專門的文檔說明,如django-tastypie.那這些文檔是怎樣生成的呢？

見http://django-tastypie.readthedocs.org/

使用Sphinx生成文檔

Sphinx是一個基於Python的文檔生成項目。最早只是用來生成Python的項目文檔，但隨着這個項目的逐漸完善，很多非Python的知名項目也採用Sphinx作爲文檔寫作工具，甚至完全可以用Sphinx來寫書。

引用一段Sphinx生成文檔的優點包括：

    豐富的輸出格式: 支持輸出爲HTML，LaTeX (可轉換爲PDF)， manual pages(man), 純文本等若干種格式
    完備的交叉引用: 語義化的標籤,並對 函式,類,引文,術語以及類似片段消息可以自動化鏈接
    明晰的分層結構: 輕鬆定義文檔樹,並自動化鏈接同級/父級/下級文章
    美觀的自動索引: 可自動生成美觀的模塊索引
    精確的語法高亮: 基於 Pygments 自動生成語法高亮
    開放的擴展: 支持代碼塊的自動測試,自動包含Python 的模塊自述文檔,等等

其實上面這麼多功能，最本質的核心還是在於Sphinx採用了輕量級標記語言中的reStructuredText作爲文檔寫作語言。reStructuredText是類似Wiki，Markdown的一種純文本標記語言，所有Sphinx的文檔其實都是擴展名爲rst的純文本文件，然後經過轉換器轉換爲各種輸出格式，並且可以配合版本控制系統輕鬆實現Diff。

readthedocs

文檔託管的平臺，能夠和常用的GIT陣營的github，HG陣營的Bitbucket交互

把github中的文檔的代碼倉庫導入到readthedocs
首先在github->repo->Admin-ServiceHooks->ReadTheDocs,激活這個選項。
readthedocs->Import 按照上邊的有關字段的提示填寫清楚，必要的Name Author Version Repo……,這裏注意 conf.py 路徑要填寫正確（source/conf.py），提交。

sphinx

文檔書寫利器，使用的是reStructuredText格式，reStructuredText簡明教程 和使用sphinx筆記

sphinx安裝過程

Sphinx安裝

首先安裝好Python環境，建議選擇Pyhon2.7.3,並且把Python及Python/Scripts目錄加入環境變量，然後只需要一行命令即可

pip install sphinx

安裝完畢之後，進入任意目錄，運行

sphinx-quickstart

會進入一個設置嚮導，根據嚮導一步一步設置文檔項目，其實必填項只有項目名稱，作者和版本，其他設置都可以一路回車：

    文檔根目錄(Root path for the documentation)，默認爲當前目錄(.)
    是否分離文檔源代碼與生成後的文檔(Separate source and build directories): y
    模板與靜態文件存放目錄前綴(Name prefix for templates and static dir):_
    項目名稱(Project name) : EvaEngine
    作者名稱(Author name)：AlloVince
    項目版本(Project version) : 1.0.1
    文檔默認擴展名(Source file suffix) : .rst
    默認首頁文件名(Name of your master document):index
    是否添加epub目錄(Do you want to use the epub builder):n
    啓用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：n
    生成Makefile (Create Makefile)：y
    生成windows用命令行(Create Windows command file):y

最後會生成Sphinx一個文檔項目必需的核心文件，包括：

readthedocs
│ make.bat
│ Makefile
├─build
└─source
　　│ conf.py
　　│ index.rst
　　├─_static
　　└─_templates

如果嚮導中的所有設置都保存在conf.py中，可以隨時調整。
Sphinx生成文檔

source目錄就是存放文檔源代碼的目錄，默認的索引頁面爲index.rst

我們嘗試來寫作第一篇文檔，在source目錄下建立helloworld.rst，內容爲：

Hello World ===========

同時編輯index.rst對應部分爲

.. toctree::
   :maxdepth: 1

   helloworld

然後在當前目錄下運行

make html

會看到build目錄下會生成HTML格式的文檔。同理我們可以make letex生成LeTex以及其他格式。