Read the Docs 从懵逼到入门

继《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 python3-pip

然后安装最新版本的 Sphinx 及依赖。

pip3 install -U Sphinx

为了完成本示例，还需要安装以下软件包。

pip3 install sphinx-autobuild
pip3 install sphinx_rtd_theme
pip3 install recommonmark
pip3 install sphinx_markdown_tables

安装完成后，系统会增加一些 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 build/html

默认启动 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 bysphinx-quickstart on Sat Oct 10 22:31:33 2020.You can adapt this file completely to your liking, but it should at leastcontain 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/indexabout

在 source 目录下新建一个名为“2020”的文件夹，在“2020”文件夹中再创建“春、夏、秋、冬”四个文件夹，并且在其中分别创建 contents.rst 文件。最后，别忘了还有要新建一个 index.rst 文件。这一步完成后，2020 目录结构如下：

2020
├── index.rst
├── 春
│   └── contents.rst
├── 冬
│   └── contents.rst
├── 秋
│   └── contents.rst
└── 夏└── contents.rst

在 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.rst contents.md

修改 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 push -u origin main

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 的构建脚本还没兼容。。。（好吧，你们操作的时候应该修好了）

《了不起的Markdown》(博文视点出品)