Sphinx+gitee+Read the Docs搭建在線文檔系統(tǒng)
Sphinx是一個功能強大的文檔生成器，具有許多用于編寫技術(shù)文檔的強大功能
gitee是一種版本管理系統(tǒng)，相比github，有著更快的訪問速度
Read the Docs是一個在線文檔托管服務(wù)， 你可以從各種版本控制系統(tǒng)中導(dǎo)入文檔
1 安裝環(huán)境
Windows系統(tǒng)
python3環(huán)境
2 Sphinx安裝與測試
2.1 基礎(chǔ)功能安裝
首先是安裝Sphinx，在windows的命令行中輸入下面的命令
2.2 創(chuàng)建測試Demo
新建一個文件夾用來測試，比如SphinxDemo，進入該文件夾，命令行中執(zhí)行下面的命令，新建一個Sphinx的項目框架。
然后會有如下的輸出，需要根據(jù)提示輸入項目名稱、作者、版本號、語言等信息
2.3 項目文件結(jié)構(gòu)
項目創(chuàng)建完成后，可以看到如下的目錄結(jié)構(gòu)：
進入source文件夾，可以看到如下結(jié)構(gòu)：
這里先簡單說明一下各個文件的作用：
build：生成的文件的輸出目錄source: 存放文檔源文件_static：靜態(tài)文件目錄，比如圖片等_templates：模板目錄conf.py：進行 Sphinx 的配置，如主題配置等index.rst：文檔項目起始文件，用于配置文檔的顯示結(jié)構(gòu)cmd.bat：這是自己加的腳本文件（里面的內(nèi)容是‘cmd.exe’）,用于快捷的打開windows的命令行make.bat：Windows 命令行中編譯用的腳本Makefile：編譯腳本，make 命令編譯時用
2.4 普通編譯
執(zhí)行如下指令
會輸出如下編譯結(jié)果：
然后到build/html文件夾下，瀏覽器打開index.html文件
可以在瀏覽器中看到測試效果：
2.5 安裝autobuild工具
上面使用make html的方式編譯，編譯完后需要打開html文件來查。
還有一種HTTP服務(wù)的方式，可以在瀏覽器器中通過ip地址來查看，該方式需要安裝自動build工具：
然后使用如下編譯指令進行編譯
編譯結(jié)果如下：
然后可以到瀏覽器中，輸入127.0.0.1:8000查看效果：
2.6 更改樣式主題
上面的測試效果，使用的是默認的主題alabaster，如果想安裝其它的主題，可以先到Sphinx的官網(wǎng)https://sphinx-themes.org/查看:
這里選用一個較為常用的主題Read the Docs，安裝這個主題首先需要在python中進行安裝，命令如下：
然后修改conf.py 文件，找到 html_theme 字段，修改為
再次編譯，查看效果：
3 修改測試程序
Sphinx默認只支持reST格式的文件，reST的使用語法介紹見：https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html
3.1 安裝markdown支持工具
如果相要使用markdown格式的文檔，還要安裝markdown支持工具，命令如下：
若要使用markdown的表格，還要安裝：
然后，還要修改conf.py 文件，找到 extensions字段，修改為:
注：支持markdown后，文檔文件可以使用markdown格式，但文檔的配置文件
index.rst還要使用reST格式
3.2 修改文檔顯示結(jié)構(gòu)
3.2.1 index文件分析
修改文檔結(jié)構(gòu)，需要修改index.rst文件，首先來看一下這個文件中的內(nèi)容：
兩個點
..+空格+后面的文本，代表注釋（網(wǎng)頁上不顯示）等號線
====+上一行的文本，代表一級標(biāo)題.. toctree::聲明的一個樹狀結(jié)構(gòu)（Table of Content Tree）:maxdepth: 2表示頁面的級數(shù)最多顯示兩級:caption: Contents:用于指定標(biāo)題文本（可以不要）最下面的3行是索引和搜索鏈接（可以先不用管）
3.2.2 修改index文件
修改soure文件夾下的index.rst文件,，這里表示添加了一個Cpp目錄，然后Cpp目錄下，鏈接的又一個index文件
然后新建Cpp文件夾，并在該文件夾內(nèi)新建若干個子類文件夾和一個index.rst文件，我新建的如下圖：
然后編輯soure/Cpp文件夾里的index.rst文件，這里表示該目錄級別下，又包含了3個子目錄，子目錄中再次通過index文件來描述子目錄中的文檔結(jié)構(gòu)：
然后再進入各個子文件夾，添加markdown格式的文檔和index.rst文件，這里以01設(shè)計模式文件夾為例：
soure/Cpp/01設(shè)計模式中的index.rst文件內(nèi)容如下，這里表示管理了2個文檔
具體的文檔，如01單例模式.md中，就可以記錄學(xué)習(xí)筆記了，示例如下：
然后就可以編譯，查看效果了。
這是主頁的效果：
這是文檔的效果：
4 項目托管到gitee
以上的操作，只能在本地的瀏覽器查看文檔，若想讓所有人都能看到，需要部署到ReadtheDocs展示，在部署之前，要把代碼托管到代碼托管平臺，這里選用gitee，國內(nèi)使用速度快。
先到gitee上（https://gitee.com/）建立一個公開的倉庫，然后將本地項目文件上傳即可，如我是建立一個名為SphinxDemo的倉庫。
在上傳文件之前，先自己寫一個.gitignore文件，用于指示編輯的文件（build目錄）不上傳到代碼倉庫，.gitignore文件內(nèi)容如下：
然后使用就是在本地的項目文件夾內(nèi)使用基本的git指令來將文件上傳到倉庫：
5 部署到ReadtheDocs展示
最后，就是借助ReadtheDocs平臺(https://readthedocs.org/)，將我們的項目分享展示。
選擇手動導(dǎo)入一個項目：
將gitee倉庫的HTTPS鏈接復(fù)制過來
填寫項目名稱，填寫gitee倉庫的HTTPS鏈接
然后就可以點擊Build version進行項目構(gòu)建了
Build成功后，點擊閱讀文檔即可查看效果
https://sphinxdemotest.readthedocs.io/en/latest/
6 搭建過程演示視頻
https://www.bilibili.com/video/BV1S5411T7Qg
