【CentOS-7.4】Sphinx + ReadTheDocs
【目標】
在不使用自己的服務器的情況下，將文章通過 Github 等代碼託管平臺，發佈到 ReadTheDocs 文檔託管平臺上。
ReadTheDocs
文檔託管的平臺，能夠和常用的 GIT 陣營的 github，HG 陣營的 Bitbucket。
Github
代碼託管
Sphinx
文檔書寫利器，使用的是 reStructuredText 格式
方法一：sphinx，github/gitlab，readthedocs
方法二：sphinx，gitee，readthedocs
方法三：sphinx，自搭建 gitlab，自建 readthedocs
【方法一】sphinx，github/gitlab，readthedocs
【方法二】sphinx，gitee，自建 readthedocs
步驟一：註冊賬號
碼雲官網地址：https://gitee.com/
步驟二：
在碼雲創建一個 repo 存放 Sphinx，【New repository】Sphinx_ReadTheDocs
步驟三：
安裝 Sphinx
# 安裝 python3
yum install python3
# 安裝 pip
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
# 更換 pip 源
pip install psm --trusted-host mirrors.aliyun.com
psm ls
psm use qinghua
# 更換虛擬環境中的源
vi /root/Pipfile
[[source]]
name = "pypi-tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
verify_ssl = true
# 安裝 Sphinx
yum install python-sphinx
pip install sphinx sphinx-autobuild sphinx_rtd_theme
sphinx-build --version
初始化
mkdir /var/www/Sphinx_ReadTheDocs
cd /var/www/Sphinx_ReadTheDocs
sphinx-quickstart
type【也可以再編輯 vi conf.py 】
> 獨立的源文件和構建目錄（y/n） [n]: y
> 項目名稱: Sphinx
> 作者名稱: UXmall
> 項目發行版本 []: 0.1
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
> 項目語種 [en]: zh_CN
目錄結構
# tree
.
├── build # 文件夾，當你執行 make html 的時候，生成的 html 靜態文件都存放在這裏
├── make.bat # 文件，
├── Makefile # 文件，編譯用，make 命令時，可以使用這些指令來構建文檔輸出
└── source # 文件夾，文檔源文件全部應全部放在 source 根目錄下
├── conf.py # 文件，Sphinx 的配置文件，是 read the docs 的配置文件；
├── index.rst # 文件，網站首頁
├── _static # 文件夾，_static 是放置一些圖片或者其他文件；
└── _templates # 文件夾，
步驟四：
將 Sphinx 生成的文檔和配置 push 到 git 代碼倉庫
A simple command-line tutorial:
# Git global settings:
git config --global user.name "xxxxxx"
git config --global user.email "[email protected]"
# Create git repository:
mkdir /var/www/Sphinx_ReadTheDocs
cd /var/www/Sphinx_ReadTheDocs
git init
git add .
git commit -m "Sphinx_ReadTheDocs Format"
git remote add origin https://gitee.com/qu6zhi/Sphinx_ReadTheDocs.git
git push -u origin master
# Existing repository?
cd existing_git_repo
git remote add origin https://gitee.com/qu6zhi/Sphinx_ReadTheDocs.git
git push -u origin master
經過以上步驟，把 Sphinx_ReadTheDocs 生成的文檔及一些配置文件等，push 到了 gitee
步驟五：
把 Gitee 中的文檔的代碼倉庫導入到 ReadTheDocs
1、配置 Gitee
# 【】爲鏈接
（1）【Repositories】
（2）【Sphinx_ReadTheDocs】
（3）【Settings】
（4）【WebHook】
（5）【Add】
URL: URL used to notify your server when a webhook is triggered.
WebHook Password/Sign: You can use WebHook Password for authentication, or use a signature key to generate a request signature for authentication. Visit “WebHook Push Data Format Instructions” to learn more .
More documentation can be found in the “Gitee WebHook Documentation”
（6）【】
2、配置 ReadTheDocs
（1）
【方法三】sphinx，自搭建 gitlab，自建 readthedocs
參考：