初次接觸 Readthedocs 是在大二的時候用到一個處理 Ribo-seq 數(shù)據(jù)的軟件，雖然也是基于 Linux 系統(tǒng)的命令行工具而且步驟繁雜，運行前要填寫很多配置信息，但是由于rp-bp有詳實可靠的在線說明文檔（圖一），所以按照作者提供的步驟一步一步來可以很容易得到結(jié)果。當時留給我印象最深的就是他的在線說明文檔，我覺得布局很簡潔，而且很方便。
當時很多軟件的說明文件是和軟件一起打包下載的，下到本地就是簡單地文本文檔，要么就是放在官網(wǎng)上，當然我要想做個小項目也沒精力去專門維護一個服務器再寫個網(wǎng)站。
所以 readthedocs 就解決了這個痛點。官方說的四個優(yōu)點如下：
那么如何利用ReadtheDocs發(fā)布自己的在線文檔？
1. 本地安裝sphinx，sphinx是基于 python3 的，但是 linux 和 macOS 都是自帶 python3 的所以不用管，直接用 pip3 安裝 sphinx 就可以安裝。
pip3 install sphinx
pip3 install sphinx_rtd_theme
其中 sphinx_rtd_theme 是要用的主題，還有其他的主題可以換，這個可以去 github 上看，有很多開源的主題，但是要注意大部分都是不允許商用的。安裝好sphinx 之后在本地新建一個文件夾然后 cd 進去，命令行執(zhí)行：
sphinx-quickstart
然后通過 y/n 做一些基本的配置，就會自動在本地生成一個項目，拿我的一個項目舉例子，結(jié)構如下：
因為篇幅原因，level 設置的是 2，source 里面的內(nèi)容都是目錄，打開之后就是.rts 文件，可以直接修改。
2. 接下來我們要做的就是填寫配置信息，有兩個配置文件需要填寫，第一個是 ./source/conf.py 另一個是 ./source/index.rst，第一個文件是 python 文件第二個文件是 rst 文件，但是由于都是配置文件所以語法沒什么要求直接修改對應的選項就可以。
conf.py 里面是在線文檔的各種信息包括主題，版本，作者，使用的語言等等，使用的語言這里支持 md 和 rts 兩種，由于我 markdown 用的比較熟，所以這里我加了‘md’。 用 markdown需要額外安裝一個 python 包。
pip3 install recommonmark
index.rst 配置的是在線文檔的結(jié)構，可以自行添加刪除，但是如果添加了某一個目錄，那么 source文件夾下也必須有相應的文件夾，里面必須包含同名的配置文件，否則編譯的時候會報錯。
3. 配置完這兩個文件之后就可以寫文檔的主體，寫哪個目錄就去source對應的文件夾下的配置文件。如果選了 md 都用 md 語法寫，如果選了 rts 就都用 rts 寫。
4. 上傳到 github。在 github 上新建一個名為 test 的 repo，然后本地 push 上去。
echo "# test" >> README.md
git init
git add .
git commit -m "Initial"
git remote add origin git@github.com:yourusename/test.git
git push -u origin master
push 的時候 ssh 不行就換 https。
5. 進入 readthedocs ， 用 GitHub 賬號可以直接登錄。這個時候 test 這個 repo 就出現(xiàn)在列表里，選擇這個 test點擊build version就可以了。
