Sphinx + 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