【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
参考：