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/zipfilereference/datamodel/types 。(注意,没有前导或尾随斜杠)

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

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

3. Sphinx 安装:

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

3.1. 安装

// 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 主题站点选择一个主题,也可以选择默认的主题(比如classicbizstyle 或者下载第三方的 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对应的包,方能设置

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