我寫博客的初衷是為了系統的構建自己的知識體系，目前使用的平台有微信公眾號，CSDN，博客園，GitHub Pages和Gitee Pages，他們都各有優缺點，整理的筆記多了之后發現這些平台不是很方便，比如公眾號，CSDN和博客園，每次寫完文章后，還需要再平台上進行編輯再發布，比較麻煩；GitHub Pages和Gitee Pages雖然可以快速發布，但是在文章系統管理上不是很方便。我希望將筆記整理成類似電子書一樣，方便搜索和管理，經過查詢資料，發現了ReadTheDocs這個文檔管理工具，比較符合我的需求。可以使用 Sphinx 生成文檔，GitHub 托管文檔，然后導入到 ReadtheDocs進行展示，本文記錄一下搭建過程。
准備條件
1、github賬號
使用github對文檔進行版本管理
2、注冊Read the Docs賬號
官網地址：https://readthedocs.org/
3、安裝Python
Sphinx是一個python工具，用於生成文檔，所以需要安裝Python環境。
Sphinx創建文檔
Sphinx是一個基於Python的文檔生成項目，開始是用來生成 Python 官方文檔的工具，更多介紹可參考官網：https://www.sphinx.org.cn/ 。
1. 安裝Sphinx
Sphinx的GitHub地址：https://github.com/sphinx-doc/sphinx
pip安裝Sphinx
$ pip install -U sphinx
2. 創建文檔
先將遠程github倉庫clone到本地，這個倉庫是你要托管文檔的倉庫，如果沒有就新建一個。
clone到本地后，在項目根目錄創建一個docs目錄，cd進入docs目錄，執行如下命令：
$ sphinx-quickstart
Welcome to the Sphinx 4.2.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: 測試開發小記
> Author name(s): hiyongz
> Project release []: 0.1.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN
Creating file D:\pythonproj\devtest\source\conf.py.
Creating file D:\pythonproj\devtest\source\index.rst.
Creating file D:\pythonproj\devtest\Makefile.
Creating file D:\pythonproj\devtest\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file D:\pythonproj\devtest\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
上面的配置可以選擇默認，稍后修改生成的conf.py配置文件即可。
設置完成后，目錄結構如下：
│ make.bat
│ Makefile
│
├───build
└───source
│ conf.py
│ index.rst
│
├───_static
└───_templates
- build 存放編譯后的文件
- source/_static 存放靜態文件
- source/_templates 存放模板文件
- source/conf.py 項目配置文件，上面的配置可以在這里面修改
- source/index.rst 首頁
3. 編譯
對rst文件進行編譯生成HTML及相關靜態文件：
$ make html
Running Sphinx v4.2.0
loading translations [zh_CN]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
index.rst文件內容會編譯到_build/html目錄下。
打開_build\html\index.html文件，下面是渲染出來的HTML頁面：
默認主題不好看，可以配置其它主題。
4. 配置主題
安裝sphinx Read the Docs主題
pip install sphinx_rtd_theme
更多主題可到官網 https://sphinx-themes.org/ 查看。
配置source/conf.py 文件：
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
重新編譯：
$ make html
打開_build\html\index.html文件，可以發現主題配置成功。
5. 配置markdown
Sphinx默認使用 reStructuredText 標記語言，由於已經習慣使用markdown進行文檔編輯，下面來配置markdown。
1) 安裝recommonmark插件
pip install recommonmark
2）安裝支持markdown表格的插件
pip install sphinx_markdown_tables
ReadTheDocs的python環境貌似沒有sphinx_markdown_tables，在構建時可能報如下錯誤：
ModuleNotFoundError: No module named 'sphinx_markdown_tables'
解決方案是在docs目錄下新建一個requirements.txt文件，寫入如下內容：
sphinx-markdown-tables==0.0.15
3）配置source/conf.py 文件
增加：
extensions = ['recommonmark','sphinx_markdown_tables']
在source目錄下創建一個markdown文件，將makdown文件名添加到source/index.rst 中
.. toctree::
:maxdepth: 2
:caption: Contents:
windows-shortcuts.md
重新編譯
4）提交上傳
.gitignore文件添加docs/build/目錄，不需要上傳這個目錄。上傳：
git add .
git commit -m "提交說明"
git push -u origin master
關聯Read the Docs
關聯Read the Docs，使其可以在線訪問文檔。
瀏覽器訪問 https://readthedocs.org/， 點擊【我的項目】-> 【Import a Project】：
選擇倉庫
點擊下一步
構建版本
構建完成后，點擊閱讀文檔
構建成功
在線文檔地址為https://devtest-notes.readthedocs.io/。
參考資料：
- https://www.sphinx.org.cn/
- https://readthedocs.org/
- https://github.com/readthedocs/readthedocs.org
- https://docs.readthedocs.io/en/stable/tutorial/
- https://www.osgeo.cn/sphinx/usage/markdown.html
- https://www.sphinx-doc.org/zh_CN/master/usage/configuration.html
- https://iridescent.ink/HowToMakeDocs/Basic/reST.html