继《GitBook 从懵逼到入门》，时隔两年，终于推出姐妹篇《Read the Docs 从懵逼到入门》。从阅读量来看，笔者已经感受到大家对 GitBook 和 Markdown 写作的关注度，所以决定再给大家介绍一种常见的文档管理方案 —— Sphinx + GitHub + Read the Docs 的文档管理方法。
简单来说，就是先用 Sphinx 生成文档，然后用 GitHub 托管文档，再导入到 Read the Docs 生成在线文档。
无论是管理技术文档、写书、写笔记，亦或想搭建一个属于你的个人知识库，都是一个不错的选择。那我们现在开始吧！
1. 背景知识
1.1 ReadtheDocs
Read the Docs 是一个基于 Sphinx 的免费文档托管项目。该项目在 2010 年由 Eric Holscher、Bobby Grace 和 Charles Leifer 共同发起。2011年3月，Python 软件基金会曾给 Read the Docs 项目资助 840 美元，作为一年的服务器托管费用。此后，受到越来越多开源社区和开发者的关注，2017年11月，Linux Mint 宣布将所有文档转移到 Read the Docs，目前 Read the Docs 已经托管了超过 90000 份文档。
- Read the Docs 网站：https://readthedocs.org/
1.2 Sphinx
Sphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档，使用 reStructuredText 格式。但随着 Sphinx 项目的逐渐完善，目前已发展成为一个大众可用的框架，很多非 Python 的项目也采用 Sphinx 作为文档写作工具，甚至完全可以用 Sphinx 来写书。
Sphinx 是 Python 社区编写和使用的文档构建工具，由 Georg Brandl 在 BSD 许可证下开发，它可以令人轻松的撰写出清晰且优美的文档。除了天然支持 Python 项目以外，Sphinx 对 C/C++ 项目也有很好的支持，并在不断增加对其它开发语言的支持，有需要的小伙伴可以持续关注。
- Sphinx 网站：http://sphinx-doc.org/
- Sphinx 使用手册：https://zh-sphinx-doc.readthedocs.io/en/latest/index.html
Sphinx（斯芬克斯）一词源自希腊语 Sphiggein，在古埃及神话中被描述为长有翅膀的怪物，大家熟知的人面狮身像就是 Sphinx 的一种。
1.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. 环境搭建
这里以 Ubuntu 为例（其他 Linux 发行版、MacOS 或 Windows 也行），首先安装 Python3、Git、Make 等基础软件。
sudo apt install git
sudo apt install make
sudo apt install python3
sudo apt install
然后安装最新版本的 Sphinx 及依赖。
pip3 install
为了完成本示例，还需要安装以下软件包。
pip3 install sphinx-autobuild
pip3 install sphinx_rtd_theme
pip3 install recommonmark
pip3 install
安装完成后，系统会增加一些 sphinx- 开头的命令。
sphinx-apidoc sphinx-autobuild sphinx-autogen sphinx-build sphinx-quickstart
3. 快速开始
3.1 创建项目
我们以建立 diary 日记文档系统为例，先创建并进入 diary 文件夹（后续所有操作都在该文件夹内）。执行 sphinx-quickstart 构建项目框架，将会出现如下对话窗口。
欢迎使用 Sphinx 3.2.1 快速配置工具。
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.
> 独立的源文件和构建目录（y/n） [n]:
首先，询问你是否要创建独立的源文件和构建目录。实际上对应两种目录结构，一种是在根路径下创建“_build”目录，另一种是在根路径下创建“source”和“build”两个独立的目录，前者用于存放文档资源，后者用于保存构建生成的各种文件。根据个人喜好选择即可，比如我更倾向于独立目录，因此输入 y。
接着，需要输入项目名称、作者等信息。
The project name will occur in several places in the built documentation.
> 项目名称: diary
> 作者名称: Rudy
> 项目发行版本 []: v1
然后，可以设置项目的语言，我们这里选择简体中文。
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.
> 项目语种 [en]: zh_CN
OK，项目创建完成！（两种目录结构分别如下）
-
Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。 -
build：生成的文件的输出目录。 -
make.bat：Windows 用命令行。 -
_static：静态文件目录，比如图片等。 -
_templates：模板目录。 -
conf.py：存放 Sphinx 的配置，包括在sphinx-quickstart 时选中的那些值，可以自行定义其他的值。 -
index.rst：文档项目起始文件。
此时我们在 diary 目录中执行 make html，就会在 build/html 目录生成 html 相关文件。
在浏览器中打开 index.html，将会看到如下页面。
当然，直接访问 html 文件不是很方便，所以我们借助 sphinx-autobuild 工具启动 HTTP 服务。
sphinx-autobuild source默认启动 8000 端口，在浏览器输入 http://127.0.0.1:8000 。但是看到的页面跟上图一样，那换个主题吧！
3.2 修改主题
打开 conf.py 文件，找到 html_theme 字段，修改为“classic”主题。
#html_theme = 'alabaster'
html_theme = 'classic'
保存！可以看到网页变成这样了
Sphinx 为我们提供了好多可选的主题，在 Sphinx Themes 都可以找到。大家最熟悉的应该是“sphinx_rtd_theme”主题，其实我们前面已经安装好了。
html_theme = 'sphinx_rtd_theme'
那就用这个主题吧！
4. 最佳实践
4.1 index.rst 语法
受篇幅限制，本文无法详细介绍 reST 语法，具体可查看官方文档 RESTRUCTUREDTEXT 简介，这里主要分析 index.rst 的内容。
.. diary documentation master file, created by
sphinx-quickstart on Sat Oct 10 22:31:33 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to diary's documentation!
=================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
- 第1-4行由
.. + 空格开头，属于多行评论（类似于注释），不会显示到网页上。 - 第6-7行是标题，reST 的标题需要被双下划线（或单下划线）包裹，并且符号的长度不能小于文本的长度。
- 第9-11行是文档目录树结构的描述，
.. toctree:: 声明了一个树状结构（toc 即 Table of Content），:maxdepth: 2 表示目录的级数（页面最多显示两级），:caption: Contents: 用于指定标题文本（可以暂时去掉）。 - 第15-20行是索引标题以及该标题下的三个索引和搜索链接。
4.2 《我的日记》
我们进入 source 目录，修改 index.rst 文件，将标题改为“我的日记”，并添加一个 about 页面。
我的日记
=================================
.. toctree::
:maxdepth: 2
:caption: Contents:
about
因此我们需要在 source 目录下新建一个 about.rst 文件，并写下内容：
关于
========
这是我的公开日记
打开浏览器，输入 http://127.0.0.1:8000，将会看到如下页面。
接下来，我们为日记添加一级子目录。先在 source/index.rst 中添加路径信息。
我的日记
=================================
.. toctree::
:maxdepth: 2
:caption: Contents:
2020/index
about
在 source 目录下新建一个名为“2020”的文件夹，在“2020”文件夹中再创建“春、夏、秋、冬”四个文件夹，并且在其中分别创建 contents.rst 文件。最后，别忘了还有要新建一个 index.rst 文件。这一步完成后，2020 目录结构如下：
2020在 2020/index.rst 文件中添加如下内容。
2020年
=================================
.. toctree::
:maxdepth: 2
春/contents
夏/contents
秋/contents
冬/contents
以及四个 contents.rst 文件的内容：
- 春/contents.rst
春季
========
春眠不觉晓，处处闻啼鸟。
- 夏/contents.rst
夏季
========
夏早日初长，南风草木香。
- 秋/contents.rst
秋季
========
秋风吹不尽，总是玉关情。
- 冬/contents.rst
冬季
========
冬尽今宵促，年开明日长。
好啦！打开浏览器看一下吧～
好啦，日记就先写到这吧！喜欢的小伙伴可以在 https://github.com/luhuadong/diary 点赞+下载。
4.3 支持 Markdown
前面我们都是用 reST 语法来操作，但如果我们想用 Markdown 写，或者有大量 Markdown 文档需要迁移怎么办呢？
虽然 Sphinx 默认不支持 Markdown 语法，但可以通过 recommonmark 插件来支持。另外，如果需要支持 markdown 的表格语法，还需要安装 sphinx-markdown-tables 插件。这两个插件其实我们前面已经安装好了，现在只需要在 conf.py 配置文件中添加扩展支持即可。
extensions = [
'recommonmark',
'sphinx_markdown_tables'
]
我们以“秋”为例，将 rst 文件修改为 md 文件。
cd 秋
mv
修改 contents.md 文件，增加一些 Markdown 语法内容：
# 秋季
秋风吹不尽，总是玉关情。
## 二级标题
### 三级标题
#### 四级标题
这是一个**段落**
| 作者 | 朝代 | 评分 |
| :--: | :--: | :--: |
| 李白 | 唐 | 100 |
噔噔！打开浏览器，完美～
5. 文档托管
5.1 上传 GitHub
首先在 GitHub 上创建一个 diary 仓库。
在本地 diary 目录中添加 README.md 和 .gitignore 文件，在 .gitignore 文件中写入下面一行。
build/
表示不跟踪 build 目录，因为我们后面将使用 Read the Docs 进行文档的构建和托管。
接着依次执行如下命令即可。
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:luhuadong/diary.git
git
5.2 网页托管
在 Read the Docs 网站 https://readthedocs.org/ 注册，并绑定 GitHub 账户。点击“Import a Project”导入项目，输入项目名称和仓库地址即可。
翻车啦，构建失败！（构建成功的话，可以通过 diary-demo.readthedocs.io 链接访问在线文档）
原因是 GitHub 从 2020年10月1日起，把主分支的名称从 master 修改为 main 了，但是 Read the Docs 的构建脚本还没兼容。。。（好吧，你们操作的时候应该修好了）
