Sphinx reST 文档基本使用

1. 概述

reStructuredText（reST）是Docutils和Sphinx使用的默认纯文本标记语言。Docutils提供了基本的reStructuredText语法，而Sphinx扩展了它以支持其他功能。

Sphinx是一个工具，它将一组reStructuredText源文件转换为各种输出格式，自动生成交叉引用，索引等。也就是说，如果你有一个目录包含一堆reST格式的文档（可能还有docs的子目录）在那里，Sphinx可以生成一个组织良好的HTML文件排列（在其他目录中），以便于浏览和导航。但是从相同的来源，它也可以使用LaTeX生成PDF文件。

2. reStructuredText指令

官档：http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

• toctree是一个reStructuredText指令，一个非常通用的标记。
• 指令可以包含参数，选项和内容。
• 在指令名称后面的双冒号后直接给出参数。
• 每个指令决定它是否可以有参数，以及有多少参数。
• 参数后面的选项以“字段列表”的形式给出。maxdepth是toctree指令的选项。
• 内容在空行后面跟随选项或参数。
• 每个指令决定是否允许内容以及如何处理内容。
• 指令的常见问题是内容的第一行必须缩进到与选项相同的级别。

2.1. reST文件扩展名(.rst)

由于reST源文件可以有不同的扩展名（有些人喜欢 .txt，有些人喜欢.rst - 扩展名可以通过配置 source_suffix 指定），不同的操作系统有不同的路径分隔符，Sphinx抽象它们：文档名称总是相对于源目录，扩展名被剥离，和路径分隔符转换为斜杠

对于文件名的例子是index library/zipfile 或 reference/datamodel/types 。(注意，没有前导或尾随斜杠)

2.2. 其他格式转换为reST文档

要转换不同的标记，Pandoc是一个非常有用的工具，另外也有相关项目支持其他格式文档（比如Docbook、Html）转换为Sphinx文档

3. Sphinx 安装：

Sphinx至少需要运行Python 3.5，以及docutils和 Jinja2库。Sphinx应该使用docutils版本0.12或一些（未损坏的）SVN中继快照。

3.1. 安装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// python3环境
$ yum install python36 python36-pip
// pip升级到最新版本pip
$ pip3.6 install --upgrade pip 
// sphinx前置条件
$ yum install python36-docutils.noarch python34-jinja2
// clone
$ git clone https://github.com/sphinx-doc/sphinx

// 基于pip安装
$ cd sphinx
$ pip3.6 install .

....
Successfully installed Jinja2 MarkupSafe Pygments Sphinx ....

4. 基础入门

1. 可以通过sphinx-quickstart快速创建一个空的项目，然后从 sphinx 主题站点选择一个主题，也可以选择默认的主题（比如classic、bizstyle 或者下载第三方的 sphinx_rtd_theme）
2. 适当配置conf.py内容
3. 进行构建make html，将直接生成一份html文档在build目录中
4. 通过配置nginx web服务器，提供html服务

注意：

• ReStructuredText文档源的Sphinx集合的根目录称为源目录，目录还包含Sphinx配置文件conf.py（配置Sphinx如何读取源代码和构建文档）
• sphinx-quickstart的脚本，设置了一个源目录，根据conf.py询问的几个问题创建了一个具有最有用配置值的默认值。
• sphinx-apidoc的自动“API文档”生成器

5. 项目构建：

可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样： make builder

此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck，通常我们是生成html档；

6. shpinx主题

内置的主题，可以直接在配置文件中通过 html_theme = "classic" 直接指定，特殊的第三方主题，还需要在配置中import对应的包，方能设置

• 主题 - allanc-sphinx
• 主题 - sphinx-rtd

7. 参考

• PIP3安装：https://pip.pypa.io/en/stable/installing/
• sphinx安装：http://www.sphinx-doc.org/en/master/usage/installation.html
• sphinx入门：http://www.sphinx-doc.org/en/master/usage/quickstart.html
• sphinx主题
  • 官档：https://sphinx-themes.org/
  • base简洁主题：https://sphinx-themes.org/html/default/classic/index.html
  • 热门第三方主题：https://sphinx-rtd-theme.readthedocs.io/en/latest/index.html