1. Sphinx 安装和使用

1.1. 概述

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

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

重点是手写文档,而不是自动生成的API文档。虽然也支持这种文档(它可以与手写内容自由混合),如果你需要纯API文档,请查看Epydoc,它也理解reST。

1.2. 基本介绍

1.2.1. Sphinx

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

1.2.2. reStructuredText指令

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

1.2.3. reST文件扩展

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

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

1.3. 安装

1.3.1. 安装要求

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

1.3.2. 安装操作

// 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
cd sphinx
pip3.6 install .
Successfully installed Jinja2 MarkupSafe Pygments Sphinx….

1.4. 项目构建

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档,像这样:

make builder

此处的“builder”是支持的构建器名,比如 html、latex linkcheck

1.5. 调试部分

environment
A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.
source directory
The directory which, including its subdirectories, contains all source files for one Sphinx project.