原文鏈接：https://www.zhoubotong.site/post/76.html 最近發現一個文檔類網站，編寫教程很合適，特地查了一下叫Read the Docs ，可以使用 Sphinx 生成文檔，GitHub 托管文檔，然後導入到 ReadtheDocs進行展示，這裡順便記錄一下搭建過 ...

原文鏈接：https://www.zhoubotong.site/post/76.html
最近發現一個文檔類網站，編寫教程很合適，特地查了一下叫Read the Docs ，可以使用 Sphinx 生成文檔，GitHub 托管文檔，然後導入到 ReadtheDocs進行展示，這裡順便記錄一下搭建過程。

環境：Sphinx + Read the Docs + 寶塔 + Github

無論是管理技術文檔、寫書、寫筆記，亦或想搭建一個屬於你的個人知識庫，都是一個不錯的選擇。廢話不多說，進入下麵正題吧！

1. 背景知識

1.1 Read the Docs

Read the Docs 是一個基於 Sphinx 的免費文檔托管項目。該項目在 2010 年由 Eric Holscher、Bobby Grace 和 Charles Leifer 共同發起。2011年3月，Python 軟體基金會曾給 Read the Docs 項目資助 840 美元，作為一年的伺服器托管費用。此後，受到越來越多開源社區和開發者的關註。

Read the Docs 網站：https://readthedocs.org/

1.2 Sphinx

Sphinx是一個基於Python的用於創建文檔的工具。它最早只是用來生成 Python 的項目文檔，使用 reStructuredText 格式。但隨著 Sphinx 項目的逐漸完善，目前已發展成為一個大眾可用的框架，很多非 Python 的項目也採用 Sphinx 作為文檔寫作工具，甚至完全可以用 Sphinx 來寫書。具有以下特征：

輸出格式：HTML(包括Windows HTML Help)，LaTeX(用於列印的PDF版本)，ePub，Texinfo, 手冊頁，純文本；
強大的交叉引用：語義標記和對函數、類、引用、術語表和類似信息的自動鏈接功能；
層次結構：簡單的文本樹定義，並能自動鏈接同級、父級和子級；
自動索引：一般索引以及語言特定模塊索引；
代碼處理：利用Pygments實現代碼高亮；
開放的擴展：支持代碼塊的自動測試,並包含Python模塊的自述文檔(API docs)等。

Sphinx使用reStructuredText作為標記語言，它的優勢來自於reStructuredText語言的強大和直接，及其解析和翻譯套件Docutils1.3 reStructuredText

reStructuredText 是一種輕量級標記語言。它是 Python Doc-SIG（Documentation Special Interest Group）的 Docutils 項目的一部分，旨在為 Python 創建一組類似於 Java 的 Javadoc 或 Perl 的 Plain Old Documentation（pod）的工具。Docutils 可以從 Python 程式中提取註釋和信息，並將它們格式化為各種形式的程式文檔。

值得註意的是，reStructuredText 是一個單詞，不是兩個，也不是三個。可以簡寫為 RST、ReST 或 reST，作為一種用於文本數據的文件格式，通常採用 .rst 作為文件尾碼。

前面提到，Sphinx 使用 reST 作為標記語言。實際上，reST 與 Markdown 非常相似，都是輕量級標記語言。由於設計初衷不同，reST 的語法更為複雜一些。

Markdown 的目標很簡單，就是為了更簡單地寫 HTML，完成 text-to-HTML 的任務。而 reST 的目標是，建立一套標準文本結構化格式用以將文檔轉化為有用的數據格式（簡單來說，就是要實現一套簡單、直觀、明確、原文本可閱讀的，且可以轉化為其他格式的文檔標記語言）。顯然，reST 的目標更大一些。

reStructuredText 網站：http://docutils.sf.net/rst.html

2. 環境搭建

所有操作系統均可使用，此處我以 Uos為例。

確保系統中已安裝 git、make、python3、python3-pip：

sudo apt-get install git
sudo apt-get install make
sudo apt-get install python3
sudo apt-get install python3-pip

然後安裝 Sphinx 及相關依賴，對於已經安裝有Python3的系統(我裝的是Python 3.7.3)，可以直接使用pip3安裝Sphinx：

pip3 install sphinx sphinx-autobuild

安裝完成後，系統會增加一些 sphinx- 開頭的命令。

sphinx-apidoc sphinx-autobuild sphinx-autogen sphinx-build sphinx-quickstart

完成安裝之後，可以在命令視窗輸入sphinx-build -h來查看sphinx的版本號和該指令的其他控制參數。

3. 快速開始

3.1 創建項目

我們以建立 wiki 文檔系統為例，先創建併進入 wiki 文件夾（後續所有操作都在該uos系統wiki文件夾內）。

執行 sphinx-quickstart 構建項目框架，將會出現如下對話視窗。

首先，詢問你是否要創建獨立的源文件和構建目錄。實際上對應兩種目錄結構，一種是在根路徑下創建“_build”目錄，

另一種是在根路徑下創建“source”和“build”兩個獨立的目錄，前者用於存放文檔資源，後者用於保存構建生成的各種文件。根據個人喜好選擇即可，比如我更傾向於獨立目錄，因此輸入 y。

接著，需要輸入項目名稱、作者等信息。

OK，項目創建完成！設置完成後，目錄結構如下：

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

Makefile：可以看作是一個包含指令的文件，在使用 make 命令時，可以使用這些指令來構建文檔輸出。
build：生成的文件的輸出目錄。
make.bat：Windows 用命令行。
_static：靜態文件目錄，比如圖片等。
_templates：模板目錄。
conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 時選中的那些值，可以自行定義其他的值。
index.rst：文檔項目起始文件。

然後我們在 wiki 目錄下執行 make html，就會在 build/html 目錄生成 html 相關文件，比如配置更新就需要重新make html生成新文件，

還可以使用sphinx-autobuild來自動重載文檔，運行下麵指令來實現：

sphinx-autobuild . _build/html

index.rst文件內容會編譯到_build/html目錄下。打開_build\html\index.html文件是渲染出來的HTML頁面，

預設主題不好看，可以配置其它主題。

3.2 配置主題

使用sphinx-quickstart指令將生成包括conf.py在內的配置文件，以及一份主文檔文件index.rst。

conf.py文件包含了該sphinx工程的所有配置選項，包括一些無法在sphinx-quickstart嚮導中進行設置的複雜選項。

更加詳細的conf.py配置內容大家可參考The build configuration file。

安裝sphinx Read the Docs主題

pip3 install sphinx_rtd_theme

更多主題可到官網查看，打開 source/conf.py 文件，找到 html_theme 欄位，修改為我們已經安裝好的主題sphinx_rtd_theme。

html_theme = 'alabaster'

html_theme = 'sphinx_rtd_theme'

另外一種修改方式可以直接用sed -i命令修改：

sed -i s/alabaster/sphinx_rtd_theme/g source/conf.py # 等同於上面直接修改了主題

在添加2行(下麵兩行按需修改，我的值修改了html_theme參數)
vim source/conf.py
import sphinx_rtd_theme
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

修改完成後執行make html重新生成頁面，現在靜態文件全路徑是在wiki/build/html/下，
打開_build\html\index.html文件，可以發現主題配置成功，為了方便演示，因為本章所介紹的ReadTheDocs搭建是在UOS系統完成，
本機用的win10，為了方便演示，在uos環境系統下的wiki目錄執行：

uos@uos-PC:/media/uos/G/web$ cd wiki
uos@uos-PC:/media/uos/G/web/wiki$ python3 -m http.server 9000
Serving HTTP on 0.0.0.0 port 9000 (http://0.0.0.0:9000/) ...

打開_build\html\index.html文件，可以發現主題配置成功。

html目錄就是文檔框架的站點目錄，大家可以用nginx或者寶塔配置功能變數名稱映射到html目錄，到這裡大家可能會問如何更新新增的頁面？很簡單：

接下來我們編寫一個測試頁面，添加一篇文章，在source目錄下新建ch01.rst，步驟如下:

uos@uos-PC:/media/uos/G/web/wiki$ ls
_build build make.bat Makefile source
uos@uos-PC:/media/uos/G/web/wiki$ mkdir source/article -p
uos@uos-PC:/media/uos/G/web/wiki$ echo "test" >>source/article/ch01.rst
uos@uos-PC:/media/uos/G/web/wiki$ sudo vim source/article/ch01.rst #隨便輸入一點文章標題