欢迎来到 reStructureText 的世界!¶

什么是 reStructuredText？ reStructuredText 是一种基于 Python 的 docutils 模块提供解析功能的标记语言。它具有以下特点：

简洁: 解析前的纯文本仍具有良好可读性。
强大: 强大的 role、directive 以及扩展系统可以极大地增强表达能力。
统一: 不论是任何平台，其解析功能都统一在 docutils 模块下。

相比流传广泛的 Markdown，reStructuredText 具有更好的表达能力、扩展能力以及稳定性。 Markdown 根据其扩展标准、具体实现、使用环境的不同，有多个社区提供了不同的 Markdown 支持。在具有丰富生态的同时，也陷入了生态分裂的窘境。

由于使用 Markdown 不可避免的表现力不足的缺点，各个实现往不同的方向寻找扩展方法。有的 Markdown 使用 {% parameters %} 形式的 shortcode 来提供扩展，如 markdown-it；有的 Markdown 将额外的功能写入解析器，如最为强大的 pandoc；有的 Markdown 试图添加新的语法，例如 latex 风格的指令。

但它们的生态是分裂的，在前者提供的扩展，后者可能未提供，或者以另一种形式提供，导致文档难以迁移。

而 reStructuredText 在这一方面拥有巨大的优势：它以及提供了一个完善的扩展开发环境。任何表达都可以通过统一的 role 或 directive API 来实现！

reStructuredText 可用于：

文档生成工具 Sphinx
静态站点生成器 Nikola
静态博客系统 Pelican

以及任何 docutils 能去到的地方。

入门 reStructuredText ¶

由于使用 reStructuredText 的情况以撰写文档居多，因此我们以 Sphinx 为入口学习 reStructuredText。要开始一个 Sphinx 项目，可以使用其提供的命令行工具 sphinx-quickstart 来创建一个模板项目。

按照命令行的指引，将在当前文件夹生成以下文件结构:

build/
source/
    conf.py
    index.rst
Makefile

其中， build 是 sphinx 的输出目录，其中按照输出格式不同划为多个文件夹，例如 html 输出将位于 build/html，对于每一种输出格式，都会生成 build/doctree，这是 sphinx 用于缓存文档结构的目录。

source 目录则是原始 reStructuredText 文档存储的位置，sphinx 将会根据其中的内容生成文档。

source/conf.py 是对 sphinx 的配置，以 Python 的形式存储配置。

source/index.rst 是整个文档的入口。

Makefile 是便于控制此文档编译的脚本，在 Windows 下会生成替代的 make.bat 脚本。你可以使用 make html 来一键生成 HTML 输出。source 目录和 build 目录其实是由 Makefile 决定的，其默认内容如下：

# Minimal makefile for Sphinx documentation

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

可以看到，输出格式以 -M <format> 选项传递给 sphinx-build 程序，build, source 目录也是它的参数。你可以在 Makefile 中修改 Makefile 变量 SOURCEDIR 和 BUILDDIR 来修改这两个目录的路径。

在 source/index.rst 中，需要有一个 toctree directive 来表达该文档的整体结构。例如，假设文件结构如下:

source/
    index.rst
    conf.py
    一篇新文档.rst
    anothor-document.rst

那么，为了将所有文档串联起来，需要在 source/index.rst 中编辑：

.. toctree::

    一篇新文档
    anothor-document

在 directive 空一行并缩进一次后的文本将被作为 content 传递给 directive，该 toctree 接收到的 content 是两行文件名（无需后缀名）。这将在目录中添加此两篇文档，并且在 index 页面上创建链接列表。

实际上，未输入 toctree 的文档也会被渲染，只不过可能无法通过超链接访问。

单篇 reStructuredText 文档的内建标记¶

toctree 是 sphinx 提供的，来自于 docutils 的内建标记可以满足单篇文档的表达需求。这些内建的标记在 reStructuredText 标记规范的总览章节已经很好地描述了，建议先去阅读第一部分。剩下的内容旨在完整地表述 reStructuredText 的规范，不需要在此时阅读。

此后地内容会尽可能地与使用时的需求对照。

reStructuredText 最基本的被识别的结构是段落。一个段落就是一段用空行与其他结构进行分隔的文本区域。在一个段落中，可以用换行来划分不同的部分，只要它们中间没有产生空行就会被解析为同一个段落。这个特性主要是考虑到在纯文本编辑器中，避免编写太长的行，以至于无法在屏幕上显示（旧的基于终端的文本编辑器可能存在此问题）。但这些文本行需要有相同的缩进 – 即它们的左边缘需要对齐。如果有缩进的段落，则在语义上表示一段引言。例如:

这是一个段落，有点短。
新的一行具有相同缩进，那么这两句是同一段。

    如果加一个缩进，那么这一段在渲染时也会缩进；
    通常用来表达引言语义。

        -- 沃・兹基硕德

缩进结束后又变成普通的段落。

渲染效果如下：

这是一个段落，有点短。新的一行具有相同缩进，那么这两句是同一段。

如果加一个缩进，那么这一段在渲染时也会缩进；通常用来表达引言语义。

– 沃・兹基硕德

缩进结束后又变成普通的段落。

在需要保留段落的换行情况时，可以在行首使用管道符 | 来创建 line block:

| 你好世界，虽然没有空行，
| 但仍然换行了。
| 而且它们在同一个段落中。

你好世界，虽然没有空行，
但仍然换行了。
而且它们在同一个段落中。

内联标记 ¶

在段落和其他块元素内，可以使用内联的文本记号来为某个片段的文本标记语义。例如 *着重*，**强调** 表达对应的语义，在默认情况下，它们在样式上会被渲染为斜体和粗体。

小技巧

你可以将内联标记想象成特殊的『括号』，并以相同的形式使用它们 – 在标记文本的前后使用它们。由空格包围或单词中间的内联标记不会被识别，详细信息参考 reStructuredText 标记规范。

实际上，这些内联标记都是 reStructuredText 角色的简写，有：

着重

实际上是 emphasis 角色，用一对单星号表示:

*着重*，:emphasis:`着重`

着重，着重

强调

实际上是 strong 角色，一对双星号表示:

**强调**，:strong:`强调`

强调，强调

字面量

实际上是 literal 角色，用一对双反引号表示:

``字面量``，:literal:`字面量`

字面量，字面量

标题参考

title-reference 角色，别名 title 或 t，它也可以用一对单反引号表示:

`入门 |a_rst|`，:title:`入门 |a_rst|`

入门 |a_rst|，入门 |a_rst|

虽然它的默认渲染样式和着重一样，都是斜体，但更重要的是语义，对吧？

一般，会这么用:

:title:`不存在的章节` [不存在的书籍]_

.. [不存在的书籍] 《冇书》

不存在的章节 [不存在的书籍]

[不存在的书籍]

《冇书》

解释性文本角色

即一对单反引号所包括的文本角色。它默认指标题参考，但可以用一个 default-role 指令更改它在接下来的文本处理中的行为:

.. default-role:: math

现在是数学角色了： `\LaTeX`

.. default-role:: literal

`现在是字面量了`

现在是数学角色了： \(\LaTeX\)

现在是字面量了

另外的内联标记需要以完整的角色形式表述，它们是：

代码

code 角色:

:code:`println!("{}", 8usize)`

println!("{}", 8usize)

默认的代码角色是回退到 literal 的，没有高亮，可以通过 role 指令创建新的代码角色以启用高亮:

.. role:: code-py(code)
    :language: python

这是一行 Python 代码： :code-py:`print(f"{8}")`

这是一行 Python 代码： print(f”{8}”)

由于 docutils 使用 pygments 作为高亮分析器，所以只能支持高亮 pygments 实现了词法分析器的语言。

你可以打开浏览器开发者工具查看上面 code-py 的 DOM 结构，可以发现已经分词了，但不知道哪里出了问题，既没有高亮，还把引号给转义了。

数学

math 角色，用来表示一段内联的数学公式:

:math:`\LaTeX`

根据生成器的配置，可能使用 MathJax, KaTeX 渲染，或者使用本地 LaTeX 编译成 SVG 嵌入。

这个得看生成器的配置，docutils 只管语义表达。 Sphinx 默认使用 MathJax，但是推荐使用以下设置配置成 \(\KaTeX\)，比前者性能高出不少：

# conf.py

上标与下标

上标是 superscript ，别名 sup，下标是 subscript，sub。由于内联标记需要与其他构造保持一个空格，因此像这样的写法是不会按预期渲染的:

He:sub:`2`:sup:`4`

He:sub:2⁴

你需要用空格隔开的同时，将空格转义以便在输出中不渲染它们:

He\ :sub:`2`\ :sup:`4`

He₂⁴

呕，在 HTML 中表达化学符号真是一件难事，我还是用 \(\LaTeX\) 吧： \(\text{He}_{2}^{4}\) 。

原始

raw 角色，表示将内容原封不动地传递给输出。这个角色不能直接使用，而是使用 role 指令定义一个新角色，并指定输出格式:

.. role:: html(raw)
    :format: html

这样，将会限制其只在 html 输出格式下以原始文本渲染该角色的内容，而在其他输出格式下，将如同注释一般不会渲染。

例如:

.. role:: raw-html(raw)
    :format: html

.. role:: raw-latex(raw)
    :format: latex

在 HTML 中，将会渲染
:raw-html:`<ruby><rb>拼</rb><rt>pin</rt><rb>音</rb><rt>yin</rt></ruby>`，
而 :raw-latex:`怎么做哦` 应该是不会在 HTML 输出中渲染的。

在 HTML 中，将会渲染拼pin音yin，而应该是不会在 HTML 输出中渲染的。

警告

raw 角色本身在某格式下的 :raw:`渲染样式` 是未定义的。

列表 ¶

有三种风格来表示一列项目。无序列表用 *, -, + 做项目符号，有序列表可以用数字、字母、罗马数字加上点（.）、右英文括号（)）或用英文括号完全包围 – 无论你偏好什么，都能识别:

*   无序 1

-   无序 2

+   无序 3

1.  有序 1

2)  有序 2)

(3) 有序 (3)

i.  有序 一

II.  有序 贰

c.  有序 three

无序 1

无序 2

无序 3

有序 1

有序 2)

有序 (3)

有序一

有序贰

有序 three

小技巧

无序列表的项目符号可以混用，只需要保持缩进即可。

但有序列表的项目符号不可混用，并且需要保持编号连续且单调。不过，你可以使用 # 符号来进行编号的自动推导:

1. 第一项
#. 第二
#. 第三

第一项
第二
第三

列表可以通过增减缩进来表达嵌套关系:

-   无序 1

    1. 可嵌套有序
    #. 有序 2

-   无序回来

无序 1
1. 可嵌套任意类型列表，例如有序列表
2. 有序 2
无序回来

超链接 ¶

reStructuredText 一个超链接需要有两个部分：引用和靶标:

引用部分需要在名称后加下划线：链接_
如果名称中包含了空格，则需要用反引号包括起来：`链 接`_。

靶标部分的下划线在名称前面：

.. _链接: https://docutils.sourceforge.io/docs/user/rst/quickref.html

如果留空，则会将靶标引至下一个块元素。

引用和靶标也可以写在同一处:

`名称 <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__

即 `name <target>`_ 的形式。前者将会渲染为显示名称，后者将会作为靶标。

靶标也有内联形式，例如:

_`靶标` 在这里，而引用将会引至前面的 靶标_ 处。

靶标在这里，而引用将会引至前面的靶标处。

隐式超链接可以将引用引至标题:

正如下面的 `标题`_ 章节所说一样。

正如下面的标题章节所说一样。

任何满足 Uri 形式的文本会在渲染流程的最后被识别为超链接:

-   https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets
-   ftp://firefox.fake-mozilla.org/

标题 ¶

标题是划分章节的依据。将单行文本缀以下划符号则构成标题。可用的符号有 #=-~:'"^_*+<>，以及反引号。需要满足长度条件：下划符号的数目与标题文本一致，（中文这类宽字符算两个字符）。

章节的大小关系与符号无关，只与符号出现的顺序有关。一般来讲，习惯用 # 做一级标题，=, - 分别做二、三级标题。

并且，可以使用双划线:

##########
双划线风格
##########

单划线风格
==========

标题本身会提供一个锚点，可以使用超链接的方式来指向本文的一个章节:

`标题`_

例子：标题。

分割线 ¶

任何四个以上的重复横线将会渲染为分割线:

----

常用指令 ¶

任何满足:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

例如:

.. image:: example.png

形式的块都将尝试作为指令解析。

紧跟着指令名之后的内容为指令的 argument，在指令后一行，添加缩进并以字段列表的形式输入的为指令的 options，在 options 后空一行，并相对指令缩进一次的输入，是指令的 content:

.. {{ 指令名 }}:: {{ argument }}
    :{{ field name }}: {{ field value }}

    {{ content }}

大概是以上这个样子。利用指令，可以：

引入资源
格式化代码块
运行 Python 代码或借用进程间通信机制调用其他代码，并将结果嵌入输出中
……

图像 ¶

插入图像可以使用 image 或 figure 指令。

image 属于直接插入图片用的，而 figure 则可以添加更详细的描述。

image 接受一个参数：图像的 Uri，如果是相对路径，则起点是当前文档。 image 可接受零个或多个选项，可选的选项有：

height: 图像高度，可以使用 reStructuredText 支持的长度单位，见 https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units
width: 图像宽度，同上。
scale: 图像缩放，使用百分比。
align: 可以是以下值之一：top, middle, bottom, left, center, right，设置图像对齐方式。
target: 如果设置，需要传入一个超链接靶标。这会让图片可点击，点击后跳转到靶标。对于 HTML，是将 img 元素放在了 a 元素内部。

.. image:: img/59498721_p0.jpg
    :height: 400px
    :width: 600px
    :scale: 50%
    :align: center
    :target: https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

figure 由 image 和一段标题（一个单行段落），以及可选的图例组成。对于基于页的媒体（如PDF），在排版时，figure 可能会浮动到合适的地方。

figure 拥有 image 所有的选项，在以下几处有所不同：

align

可传入 left, center, right。只能设置水平方向上的对齐方式。

figwidth

设置图像宽度，这将影响图像标题和图例的折行方式，以确保它们的宽度不会超过这个值。但是这并不影响内嵌的图片宽度，图片的宽度需要用 width 选项设置:

+---------------------------+
|        figure             |
|                           |
|<------ figwidth --------->|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |<--- width --------->|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+

表格 ¶

除了网格式和简单式的表格之外，还可以使用 list-table 或 csv-table 来创建表格，和前两种相比，后两种比较不美观，但是不需要做 “字符画” 了。

table

table 指令的内容可以是任意表格，包括 grid table, simple table 以及通过 list-table, csv-table 创建的表格。

它的作用主要是为表格添加标题，以及设置一下各列的宽度。

接受以下选项：

widths: 可以是 auto, grid 或用一列整数（用逗号或空格分隔）设置各列的宽度（按字符数计算）。如果传入 auto 或 grid，则由后端来推测列宽。
width: 表格整体的宽度。如果忽略，则由后端自动推测。
align: 表格整体的对齐方式。left, center, right。

csv-table

从 CSV 数据创建表格:

.. csv-table:: Frozen Delights!
    :header: "Treat", "Quantity", "Description"
    :widths: 15, 10, 30

    "Albatross", 2.99, "On a stick!"
    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
    crunchy, now would it?"
    "Gannet Ripple", 1.99, "On a stick!"

以下选项可被识别：

widths

auto 或一组整数，设置列宽。默认每列一致。

width

整体的宽度。

header-rows

整数，表示接下来的 CSV 数据中前几行为表头。默认 0.

header

一列 CSV 内容，用作表头。将插入到 header-rows 所设定的行前面。

stub-columns

整数，表示 CSV 数据中左几列为存根。默认 0.

file

从文件系统读取 CSV 数据。

url

从网络地址读取 CSV 数据。

encoding

设置外部 CSV 数据的字符编码。默认和当前文档相同。

delim

分隔符，默认逗号 ,。

quote

括号，用来包括表格中的单元。默认双引号 "。

keepspace

保留分隔符旁的空白。默认忽略。

escape

转义符号。默认是将需要转义的字符重复两遍:

"He said, ""Hi!"", and go away."

align

水平对齐方式。

list-table

用列表的形式来创建表格。列表的顶级项表示一行，次级项表示一行的各元素:

.. list-table::

    *   -   表头1
        -   表头2
        -   表头3
    *   -   内容11
        -   内容12
        -   内容13
    *   -   内容21
        -   内容22
        -   内容23

表头1	表头2	表头3
内容11	内容12	内容13
内容21	内容22	内容23

可接受 widths, width, header-rows, stub-columns, align 选项。

目录 ¶

contents 指令可以渲染出该篇文档的目录:

.. contents::

可接受以下选项：

depth: 整数，设置目录层级深度，默认无限。
local: 如果提供，则会生成该章节以及子章节的目录而非全篇目录。
backlinks: 是否生成目录项和文档项之间的链接。

替换引用 ¶

替换引用可以将一个指定的片段替换为另一个结构。

替换文本

.. |a_rst| replace:: `restructuredtext <https://docutils.sourceforge.io/docs/>`__

然后使用 |a_rst|，渲染时将被替换。

然后使用 reStructuredText，渲染时将被替换。

Unicode

.. |c| unicode:: 0xa9

这是版权符号 |c|，Unicode 码点是 169，用十六进制表达就是 0xa9。

这是版权符号 ©，Unicode 码点是 169，用十六进制表达就是 0xa9。

可以使用三个选项：

ltrim, rtrim, trim: 是否移除左、右、两侧的空白字符。

时间日期

.. |date| date::

.. |time| date:: %H:%M:%S

将会渲染为编译文档时的时间日期，可以用 Python 标准库 time 中 strftime 相同的
格式化字符串设置渲染格式。
默认是当前日期 |date|，可以用 ``%H:%M:%S`` 渲染为当前时间 |time|。

将会渲染为编译文档时的时间日期，可以用 Python 标准库 time 中 strftime 相同的格式化字符串设置渲染格式。默认是当前日期 2020-04-06，可以用 %H:%M:%S 渲染为当前时间 03:47:03。

警告 ¶

reStructuredText 提供了一些警告指令，如

attention
caution
danger
error
hint
important
note
tip
warning

用来将传入的体元素表达为指定的语义。:

.. warning::

    毫无营养的随便写写是没有意义的！

警告

毫无营养的随便写写是没有意义的！

比较通用的是 admonition 指令，上述指令其实是它的子类。:

.. admonition:: 标题
    :class: 类型，用于决定渲染样式

.. admonition:: 你瞅啥？
    :class: dongbei warning

    瞅你咋地？

你瞅啥？

瞅你咋地？

导入 ¶

可以将外部文档导入进来，使用 include 指令。

将外部文档作为 reStructuredText 导入，使用相同的渲染方式:

.. include:: path/to/document.rst

相对路径的起点是当前文档所在的文件夹。可接受以下选项：

start-line: 整数，从文件的第几行开始读取。和 Python 一样，第一行的索引值是 0 。
end-line: 整数，到文件的第几行结束。第一行零。
start-after: 字符串，将从文件中第一次找到的指定字符串后开始读取。
end-before: 字符串，将在文件中第一次找到的指定字符串前结束。
encoding: 字符编码。
literal: 是否以纯文本字面量的形式导入。
code: 输入 Pygments 支持的分词器名，以指定语言的词法规则将导入内容格式化。
number-lines: 整数。设置第一样的行号。仅在 literal 或 code 选项被设置时工作。
tab-width: 整数。设置制表符所渲染的空格的数目。仅在 literal 或 code 选项被设置时工作。

原始输入 ¶

raw 指令将其内容在指定的输出格式下原样传递给输出:

.. raw:: html

    <hr width=50 size=10>

可选参数：

file: 从文件系统中读取内容。
url: 从网络读取内容。
encoding: 外部内容的字符编码。

类 ¶

class 指令用于声明其内容或接下来的内容的类型。对于 HTML 输出而言，这会在其内容的 class 属性中添加指定的名称。

.. class:: special

一个『特殊的』段落。

.. class:: exceptional remarkable

一个『例外』的章节
==================

这是个普通段落。

.. class:: multiple

    如果要传递内容，那么需要是体元素。
    比如一个或多个段落。

    这是第二段。

上面的渲染效果用一段伪 XML 来表示:

<paragraph classes="special">
    一个『特殊的』段落。
<section classes="exceptional remarkable">
    <title>
        一个『例外』的章节
    <paragraph>
        这是个普通段落。
    <paragraph classes="multiple">
        如果要传递内容，那么需要是体元素。比如一个或多个段落。
    <paragraph classes="multiple">
        这是第二段。

配置角色 ¶

可以使用 role 来创建一个新的角色，使用 default-role 来配置解释性文本角色的默认含义。

.. role:: custom

An example of using :custom:`interpreted text`.

定义必须在使用的前面。可以用一个括号来表达继承关系（类似 Python 的 class）:

.. role:: custom(strong)

:custom:`强调`。

特殊的例子是 raw 角色，它必须继承后使用:

.. role:: raw-html(raw)
    :format: html

:raw-html:`<br>`

.. default-role:: math

会将之后的默认角色设置为 math，例如 `\LaTeX` 和 :math:`\LaTeX` 是一样的含义了。

对任何指令都同样的选项 ¶

任何指令都可设置 class 和 name 选项，前者效果与类相同，后者会将该结构设置成一个可超链接的锚点:

.. image:: bild.png
    :name: my picture

在文章中可以使用 `my picture`_ 来链接至上面的图片。
它的效果和

.. _my picture:

.. image:: bild.png

是一样的。

常用角色 ¶

在内联标记章节已经介绍了一部分，接下来是

doc: 这会创建一个引向项目中其他

reStructuredText 标记规范¶

reStructuredText 是一个使用简单且直觉化的构造来表述文档结构的标记语言。这些结构既易读易写又容易处理。这篇文档自己就是 reStructuredText 的一个例子。 reStructuredText 的解析器是 docutils 的一个组件。

简单的隐式标记被轧来表述特殊构造，例如章节标题、项目列表、强调等等。使用的标记尽可能地最小且不引人注意。基本的 reStructuredText 尽量使用较少的构造而扩展使用更复杂的显式标记。

reStructuredText 适用于任意长度的文档，从非常短（嵌入式的文档片段）到非常大（如本文档）。

第一个章节给出了一个快速总览，完整的规范在语法描述章节给出。

字面块（不会解析标记）被用来展示例子，表明标记的纯文本形式。

总览¶

一篇 reStructuredText 文档是由体或块级元素组成的，并可以使用章节来组织。 `章节标题`_ 可以使用下划线或可选的上划线风格标记。章节可以包含 body 与子章节。一些体元素可以包含进一步的元素，例如列表包含列表，列表包含段落或其他块元素等等。作为一个段落，可以包含文本与 `行内标记`_ 元素。

这里有一些体元素的例子：

段落与行内标记

段落包含文本与行内标记：*着重*，**更着重**，`解释型文本`，``行内字面量``，
独立超链接（https://www.python.org），外部超链接（Python_），交叉引用（example_），
脚注（[#1]_），引文引用（[CIT2002]_），替换引用（|example|），以及行内链接目标
_`inline iternal targets`。

段落使用空行划分，左对齐。

几种列表

无序列表

-   这是无序列表，使用项目符号做前缀，每一条项目跟在后面
-   项目符号可以使用 ``*``, ``+`` 或 ``-``

有序列表

1.  这是有序列表
2.  有序列表可以使用数字、字母或罗马数字为前缀
#.  也可以使用 ``#`` 符号让之后的编号自动推导

定义列表

这是什么
    定义列表将术语与它的定义联系起来。

如何编写
    术语是一个单行文本，定义则是紧跟在其后的一个或多个段落或其他体元素。
    定义需要比术语多一个缩进。

字段列表

:啥: 字段列表将字段名映射为字段体，就像数据库记录一样，通常作为扩展语法的一部分。

:怎样: 字段名标记是一个冒号+字段名+冒号

    字段体可以是一个或多个体元素，第一个体元素可以跟在字段名后面，多余的需要比字段名多一个缩进。

选项列表

主要用来列出一个命令行程序的命令行选项:

-a              command-line option "a"
-b file         options can have arguments
                and long descriptions
--long          options can be long also
--input=file    long options can also have
                arguments
/V              DOS/VMS-style options too

选项和它的帮助信息之间需要至少有两个空格的间隔。

字面量块

字面量块是一个缩进或行前缀引言的块，在前一个段落的末尾需要有一个双冒号 ``::``
（就像这样 -->）::

    printf("%s", "Hello World!");

块引言

块引言由一个缩进的块元素组成：

    Everyone will going to die, but several of them need a little help.

        -- Lucian

文档测试块

专门用于 Python，执行文档测试:

>>> print("Hello World!")
Hello World

两种表格语法

网格表格

完整，但复杂而详细:

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

简单表格

小而紧凑，但是受限:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

显式标记块

都以一个显式标记块符号（两个点加一个空格）开始：

脚注:

.. [1] 一个脚注由标签和一个或多个体元素组成。
    标签可以是纯数字或一个井号后接文字（``[#fn-example]``）。

    标签的引用需要在标签后加一个下划线： ``[1]_``，渲染出的效果和标签内容无关，而是自动编号。

    另外的体元素一贯地需要缩进一次。

引文:

.. [CIT2002] 和脚注一样，除了标签是文字的。引用处的标签也是文字。

超链接目标:

.. _Python: https://www.python.org/

.. _example:

    上面的 _Python 将会引向一处网址，而 _example 则是此段落。

指令（Directive）:

.. image:: img/59498721_p0.jpg

替换定义:

.. |替换| replace:: 文本

注释:

.. 任何不满足标记规则的显式标记块都是注释，不会出现在输出中。

以下是上述例子的渲染效果：

段落包含文本与行内标记：着重，更着重，解释型文本，行内字面量，独立超链接（https://www.python.org），外部超链接（Python），交叉引用（example），脚注（[1]），引文引用（[CIT2002]），替换引用（文本），以及行内链接目标 inline iternal targets。

段落使用空行划分，左对齐。

这是无序列表，使用项目符号做前缀，每一条项目跟在后面
项目符号可以使用 *, + 或 -

这是有序列表
有序列表可以使用数字、字母或罗马数字为前缀
也可以使用 # 符号让之后的编号自动推导

这是什么: 定义列表将术语与它的定义联系起来。
如何编写: 术语是一个单行文本，定义则是紧跟在其后的一个或多个段落或其他体元素。定义需要比术语多一个缩进。

啥:

字段列表将字段名映射为字段体，就像数据库记录一样，通常作为扩展语法的一部分。

怎样:

字段名标记是一个冒号+字段名+冒号

字段体可以是一个或多个体元素，第一个体元素可以跟在字段名后面，多余的需要比字段名多一个缩进。

`-a`	command-line option “a”
`-b file`	options can have arguments and long descriptions
`--long`	options can be long also
`--input=file`	long options can also have arguments
`/V`	DOS/VMS-style options too

字面量块是一个缩进或行前缀引言的块，在前一个段落的末尾需要有一个双冒号 :: （就像这样 –>）:

printf("%s", "Hello World!");

块引言由一个缩进的块元素组成：

Everyone will going to die, but several of them need a little help.

– Lucian

>>> print("Hello World!")
Hello World

Header row, column 1	Header 2	Header 3
body row 1, column 1	column 2	column 3
body row 2	Cells may span

Header row, column 1	Header 2	Header 3
body row 1, column 1	column 2	column 3
body row 2	Cells may span columns

[1]	一个脚注由标签和一个或多个体元素组成。标签可以是纯数字或一个井号后接文字（`[#fn-example]`）。标签的引用需要在标签后加一个下划线： `[1]_`，渲染出的效果和标签内容无关，而是自动编号。另外的体元素一贯地需要缩进一次。

[CIT2002]

和脚注一样，除了标签是文字的。引用处的标签也是文字。

上面的 _Python 将会引向一处网址，而 _example 则是此段落。

语法描述¶

下面的描述列出了与语法构造相对应的 “doctree元素” （文档树元素名称； XML DTD通用标识符）。有关元素层次结构的详细信息，请参阅 Docutils文档树和 `Docutils通用DTD XML文档类型定义<https://docutils.sourceforge.io/docs/ref/docutils.dtd>`__。

reStructuredText 角色¶

https://docutils.sourceforge.io/docs/howto/rst-roles.html

reStructuredText 指令¶

https://docutils.sourceforge.io/docs/ref/rst/directives.html

reStructuredText 扩展小册¶

reStructuredText 可以添加扩展，定义新的解释结构的规则。新的扩展以指令和角色的形式提供。

reStructuredText 的扩展是使用 Python 编写的。

graphviz¶

见 https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html

语法¶

可以使用指令:

.. graphviz:: /code/example.gv

来包含一个用 graphviz 语法编辑的文件, 将在构建时渲染为图片.

或者用同样的指令:

.. graphviz::

    digraph foo {
        "bar" -> "baz";
    }

或者用子指令, 分别生成有向图与无向图:

.. digraph:: 名字

    foo -> bar;

.. graph:: 另一个名字

    foo -- bar;

配置¶

在 conf.py 中的 extensions 列表中添加项目 "sphinx.ext.graphviz" 以启用本插件.

graphviz_dot 设置渲染器路径, 默认为 dot, 如果下载安装的 graphviz 套件未添加进 PATH, 那么需要完整的绝对路径.
graphviz_dot_args 传递给渲染器的命令行参数, 应该为一个列表, 类似于 sys.argv, 或者说 argparse 所解析的格式. 默认为空列表 [].
graphviz_output_format 设置构建 HTML 时的输出格式, 默认为 'png', 必须在 'png' 或 'svg' 中二选一. 如果选择了 svg, 那么为了使图片超链接正常工作, 需要在代码中指定相关的 HTML 属性:
```
.. graphviz::

    digraph example {
        a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
        b [label="other"];
        a -> b;
    }
```

使用 Sphinx 生成 LaTeX 文件 (最终得到 PDF)¶

在 LaTeX 设置中, 设置以下参数:

latex_engine = "xelatex"
latex_elements = {
    'papersize': 'a4paper',
    'utf8extra': '',
    'inputenc': '',
    'cmappkg': '',
    'fontenc': '',
    'preamble': r'''
        \usepackage{xeCJK}
        \parindent 2em
        \setcounter{tocdepth}{3}
        \renewcommand\familydefault{\ttdefault}
        \renewcommand\CJKfamilydefault{\CJKrmdefault}
    ''',
}

就能获得良好的 TeX 代码输出, 进入到 build/latex 目录下 make, 就能自动调用 xelatex 编译 PDF 了

注意, make 文件中, 查找的 LaTeX 文件与这个设置有关:

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 文件名, 封面标题,
    author, 'manual'),
]

在文件名中, 最好不要有非 ASCII 字符, xelatex 恐怕无法找到含还有中文字符的文件名.

默认情况下, 生成的 PDF 是双页打印模式的, 在电脑上浏览会发现有很多空白, 这是那些左侧有文字, 右侧没有内容, 且下面的内容在下一个章节的情况下, 会留空.

要设置这一点, 在 latex_elements 中添加一项

latex_elements = {
    'extraclassoptions': 'openany,oneside',
}

那么, 就会按照单页样式打印.

matplotlib¶

语法¶

提供了 plot 等指令.

plot¶

见 https://matplotlib.org/devel/plot_directive.html

plot 可以包含一个编写 matplotlib 作图的 Python 代码, 并将其渲染为图形. 同样也可以在下方一个缩进单位的区块中直接编写代码:

.. plot:: _code/sinx.py
    :include-source:

    添加一些描述(可选的)

.. plot::

    import matplotlib.pyplot as plt
    import numpy as np

    x = np.linspace(-6, 6, 1000)
    y = np.sin(x)
    plt.plot(x, y)
    plt.title("sin(x)")

    # 最后必须要调用 show 方法, 才能显示
    plt.show()

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(-6, 6, 1000)
y = np.cos(x)
plt.plot(x, y)
plt.title("cos(x)")
# 最后必须要调用 show 方法, 才能显示
plt.show()

(Source code)

添加一些描述(可选的)

(Source code)

默认会生成 png, big png, pdf 三种格式的图片.

可以给 plot 指令使用参数 :include-source: 将源代码插入到图片上方.

配置¶

需要在conf.py 文件的 extension 列表中添加项目 'matplotlib.sphinxext.plot_directive' 项目, 以启用 plot 指令.

其他可设置项:

`plot_pre_code`¶

在每幅图的代码中都会首先执行的代码, 设置后将不需要在代码中重复书写:

plot_pre_code = """
import numpy as np
import matplotlib.pyplot as plt
"""

`plot_include_source`¶

设置每幅图的 :include-source: 选项的默认值:

plot_include_source = False

`plot_basedir`¶

生成图像的默认储存位置, 默认为代码文件所在目录:

plot_basedir = 'img/'

域¶

所谓的域其实就是用来描述代码中结构的指令.

sphinx 直接支持的代码域有 Python, C, C++, JavaScript. 并且还支持 reStructuredText 与 Math 域.

其他可用的域以插件方式提供, 参见 More Domains

reStructuredText 自定义扩展¶

reStructuredText 提供了基于 docutils 模块的扩展支持能力。扩展以 Python 代码编写，以新的指令或角色的形式提供。由于 Python 的能力，还可以调用外部程序对内容进行处理。

在编写扩展之前，建议先掌握加载扩展的方法，这里提供一份 HelloWorld 扩展的代码，作用是提供 helloworld 指令，将该指令转换为形如 Hello World! {{ 时间日期 }} 的段落：

from docutils import nodes
from docutils.parsers.rst import Directive
from time import localtime, strftime
class HelloWorld(Directive):
    def run(self):
        datetime = strftime("%Y-%m-%d %H:%M:%S", localtime())
        paragraph = f"Hello World! {datetime}"
        return [nodes.paragraph(text=paragraph)]

本文提供了 Sphinx 的扩展加载方式和 Nikola 加载插件的方式。请在阅读这两个章节之一并成功运行上面的例子后，阅读后续的编写扩展章节。

Sphinx 加载扩展¶

Sphinx 的扩展可以通过预安装的包的形式来加载，也可以放置在当前项目的 source/_ext 目录下， _ext 目录名前的下划线是告诉模板引擎此文件夹内容不渲染，也可以将此文件夹任意取名，我们将在 source/conf.py 中配置它。

在 source/conf.py 中，通过 Python 的功能将扩展所在的文件夹加载到路径中，然后配置 extensions 变量，在列表中添加模块名：

# ...
import sys
from pathlib import Path
sys.path.insert(0, Path("_ext").absolute().as_posix())
# ...
extensions = [
    "helloworld"
]

为了让 Sphinx 加载此扩展，你需要在上面提供的功能代码 ext_helloworld 的基础上再添加一个 setup 函数：

from docutils import nodes
from docutils.parsers.rst import Directive
from time import localtime, strftime
# 提供智能提示
from sphinx.application import Sphinx


class HelloWorld(Directive):
    def run(self):
        datetime = strftime("%Y-%m-%d %H:%M:%S", localtime())
        paragraph = f"Hello World! {datetime}"
        return [nodes.paragraph(text=paragraph)]


def setup(app: Sphinx):
    """Sphinx 使用的加载函数

    :param app: Sphinx 应用
    :type app: sphinx.application.Sphinx
    :returns: 该扩展的配置信息
    """
    app.add_directive("helloworld", HelloWorld)
    return {
        'version': '0.1',
        # 允许并行读取
        'parallel_read_safe': True,
        # 允许并行写入
        'parallel_write_safe': True,
    }

.. helloworld::

Hello World! 2020-04-06 03:47:03

Nikola 加载插件¶

编写扩展¶

扩展的两种形式：Directive 和 Role。前者是 docutils.parsers.rst.Directive 实例，后者可以通过一个函数来加载。

创建一个角色¶

我们先了解一下角色的创建方式，可以参考官方文档创建 reStructuredText 解释性文本角色 https://docutils.sourceforge.io/docs/howto/rst-roles.html 。

一个角色是一个函数：

role_function(name, rawtext, text, lineno, inliner, options={}, content=[])¶

参数:

name (str) – 该角色的名称
rawtext (str) – 包含该角色完整标记的纯文本，常用来在发生错误时通过 problematic 结点来抛出错误信息。
text (str) – 该角色的内容
lineno (int) – 该角色在源文件中所处的行数
inliner – 调用该函数的 docutils.parsers.rst.states.Inliner 对象，提供报告错误和访问文档树的一些有用的属性。
options (Dict[str, str]) – 通过 role 指令创建的角色会传入此参数，是 role 指令设置的选项和它们的值。
content (List[str]) – 通过 role 指令创建的角色会传入此参数，是 role 指令的内容。 TODO:（截至 2012 年官方文档撰写时，没有角色会使用此参数)

返回:

一个元组，包含两个元素：

一组结点，将被插入到文档树中角色出现的位置。
一组系统信息，将被插入到文档数中角色出现的块的后一个块中。

它们都可以是空列表。

返回类型:

Tuple[List[nodes], List[messages]]

以下面的角色为例:

:github:`zombie110year/learn-rst`

当调用时，各参数的值将是

name

github

rawtext

:github:`zombie110year/learn-rst`

text

zombie110year/learn-rst

lineno

看情况，从 0 开始。

对于一个标准的角色，需要用 register_canonical_role 将其注册进 docutils 的解析器中：

docutils.parsers.rst.roles.register_canonical_role("github", github_role)

如果该角色是与所使用的应用程序相关的，则需要使用 register_local_role 函数来注册：

from docutils.parsers.rst import roles
roles.register_local_role(name, role_function)

另外还提供一个 register_generic_role 的注册函数，这个函数是为了便于将那些只是将文本处理为某个结点的角色注册的，这样的角色没有其他功能：

from docutils.parsers.rst import roles, nodes
roles.register_generic_role("emphasize", nodes.emphasis)

对于我们的 github 角色 Github - zombie110year/learn-rst 来说，我们的目的就是将它转换成链接到 GitHub 仓库的链接，那么就可以这么编写：

from docutils.parsers.rst import nodes
from docutils.parsers.rst import roles
from docutils.parsers.rst.states import Inliner
def github_role(name: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options={}, content=[]):
    """格式化为链接
    """
    # 判断是仓库还是用户
    title = f"Github - {text}" if "/" in text else f"{text}@GitHub"
    url = f"https://github.com/{text}"
    # 返回一个超链接结点
    return [nodes.reference(rawsource=rawtext, text=title, refuri=url)], []

这个功能将会判断我们提供的是一个仓库的名称还是一个用户的名称，并且格式化为不同的显示名。例如:

本仓库为 :github:`zombie110year/learn-rst`，
它的创建者是 :github:`zombie110year`。

本仓库为 Github - zombie110year/learn-rst，它的创建者是 zombie110year@GitHub。

Nikola 静态网站生成工具¶

Sphinx 文档生成工具¶

Sphinx 简单入门¶

Sphinx 是一个用于生成 Python 文档的工具, 但是也可以用来制作电子书. 本文记录使用该工具的一些经验.

首先使用 Sphinx 的自动配置工具¶

在准备好的工作目录下, 运行 sphinx-quickstart 将会弹出一堆文本, 并让你在其中选择要使用的配置, 一般情况下, 只需要手动修改两项, 其他保持默认即可. 让我们来看看 Sphinx 询问了我们哪些问题吧.

Welcome to the Sphinx 1.8.1 quickstart utility.

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.
> Separate source and build directories (y/n) [n]: y

是否将源文件(使用 .rst 或 .md 标记语言写的文档)和生成文件(html 或 epub, pdf 等)分开放置在不同的目录

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

对于模板或静态目录(文件不被解析渲染), 设它们的前缀为 _.

The project name will occur in several places in the built documentation.
> Project name: Learn-Sphinx
> Author name(s): Zombie110year
> Project release []:

分别是项目名, 作者名, Project release 是指项目发布版本, 根据实际项目来填.

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
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: zh_CN

选择项目语言, 默认是英语, 用 zh_CN 表示简体中文, 可以在上面那个链接看支持的语言以及其表示代码. 这个选项会影响搜索功能, 英文情况下, 会以英语存储搜索索引, 这样就无法使用中文搜索. 搜索功能是用 JavaScript + 字典实现的.

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

文档文件后缀, 只有拥有这些后缀的文件才会被解析, 在当前使用的版本(v1.8.2)中只能接受 .rst 与 .txt 后缀(但都是以 reStructuredText 的语法进行解析). 要解析 Markdown, 需要安装额外的插件 recommonmark, 这个稍后再讲.

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

这个是主文件, 对于 html, 就是指 index.html 等能够被浏览器直接默认显示的. 建议保持默认.

接下来就是插件配置. 这里的都是默认插件, 其中 imgmath 和 mathjax 不能同时选.

Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: n
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y

然后询问是否创建 Makefile 或者 Windows 的批处理脚本, 这是为了方便使用 make xxx 来构建文档.

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: y

就算在 quickstart 中有选项不满意, 也可以在接下来的 conf.py 中修改.

如何规划目录结构¶

在运行了如上的 sphinx-quickstart 程序后, 目录下出现了以下文件/目录:

├─build
└─source
    ├─_static
    ├─_templates
    |  conf.py
    |  index.rst
  Makefile

在根目录下设置了 Makefile 便于使用 make 工具自动构建, 而配置文件和索引则放在了 source 目录下. 如果需要修改文件规划, 那么, 可以在 Makefile 中修改 BUILDDIR 和 SOURCEDIR 两项目.

插件介绍¶

Sphinx（docutils）的插件都以 Python 模块的形式提供， sphinx 的插件是位于 sphinx.ext. 模块下的子模块。

官方插件¶

autodoc: 自动从模块中抽取 docstring 插入文档
apidoc: 根据源代码中的注释或文档字符串生成 API 文档
autosectionlabel: 自动为文章中的标题生成链接，方便引用
coverage: 检查代码文档覆盖率
doctest: 在编译文档时执行文档测试
extlinks: 方便编辑指向同一网站下页面的链接
githubpages: 为了发布在 Github Pages 上，创建 .nojekyll 文件以禁用 jekyll
graphviz: 调用 graphviz 生成图片
ifconfig: 通过配置的条件判断决定文档包含
imgconverter: 编译前转换图片
imgmath: 将数学公式渲染为 png 或 svg 图像
inheritance_diagram: 解析对象继承关系并生成图形
intersphinx: 链接官方文档需要启用它才能使用 os 这样的语法链接到官方文档
mathjax: 使用 Mathjax 渲染数学公式
todo: 渲染 todo 域，根据配置的不同决定是否在输出结果中包含 todo 内容
viewcode: 将源代码包含进文档项目, 并在 api 文档中创建指向源代码的链接

第三方插件¶

第三方插件通常在 sphinxcontrib 包中，数量庞大，功能众多，感兴趣可以自己去看，另外有些 Python 项目会在自己的包内提供 sphinx 扩展，例如

matplotlib, 在文档中嵌入 matplotlib 代码, 在构建时生成图片

toctree¶

在 source 目录下添加 .rst 文件, 但是如果要在编译项目后从首页 (index.html) 进行访问, 还需要在 index.rst 中将这个文件添加到 toctree 中. 在原始的 index.rst 中, 应当有如下 toctree.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

要在 toctree 中添加一个文件, 应当在上面那个 toctree 结构下空一行, 添加文件名(不需要扩展)

例如, 有一个 example.rst 就将 toctree 编辑为

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   example

如果, 在 source 目录中, 添加了子目录, 将文档放在子目录里了, 那么, 只需要在原来 example 里面按相对于 index.rst 的路径填就可以了, 例如 /source/text/example.rst 就填:

.. toctree::
   :maxdepth: 2

   text/example

toctree 参数¶

toctree 下的 :maxdepth: 2, :caption: Contents: 等就是它的参数, 可以选用的参数有:

:maxdepth: n 将目录的标题深度设为 n. 意思是 example 文件为目录的根标题, 在这个标题下, 会建立文件中的 1, 2, …, n 级标题的索引.
:numbered: 给标题自动编号.
:caption: xxx

更改 html 页面主题¶

默认的 html 页面看起来并不是很好看, 可以使用 pip 安装 sphinx_*_theme 等包, 然后在 conf.py 中引用, 就可以使用更多的主题.

例如 sphinx_rtd_theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/ 这个受很多人欢迎的主题.

# 下载
pip install sphinx_rtd_theme

# conf.py 中配置
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'

在 GitHub Page 上展示文档¶

在使用 Sphinx 构建完毕后, 生成的 html 项目可以直接拿来用.

GitHub Page 可以将 master, gh-pages 分支下的根目录或 master 分支的 /doc 目录渲染成页面.

为了方便管理, 可以在 build/html 目录下新建一个 git 仓库, 并重命名为 gh-pages 分支. 将这个分支 push 到 github 的 gh-pages 上, 充当 GitHub Page 的资源. (注意, build 目录应当在根目录下的 .gitignore 中被忽略)

这样, 在项目根目录只需要一个 master 分支, 在这个分支编辑源文件, 然后 make html, git add *, git commit, git push, 之后就进入 build/html 目录, 再 git 一通即可. 非常舒服.

使用 Sphinx 书写 API 文档¶

程序中有哪些结构? 变量,函数,类 …… 等等. 在 Sphinx 中定义了相应的指令或角色来描述它们, 并且, 也可以写进源代码的 docstring 中, 让 sphinx-apidoc 自动生成.

此文参考官方文档 http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html .

函数¶

getDate(time, mode="YYYY-MM-DD hh:mm:ss")¶

解析传入的时间, 得到一个可读的时间字符串.

参数:	time (int) – 从 1970 至今的秒数 mode (str) – 解析模式
返回:	表示时间的字符串 `YYYY-MM-DD hh:mm:ss`
返回类型:	str
引发:	ValueError – 不能传入一个负值
变量:	test – 一个无关的测试量

使用 function 描述一个函数:

.. function:: getDate(time, mode)

    解析传入的时间, 得到一个可读的时间字符串.

    :param int time: 从 1970 至今的秒数
    :param mode: 解析模式
    :type mode: str

    :return: 表示时间的字符串 ``YYYY-MM-DD hh:mm:ss``
    :rtype: str

    :raise ValueError: 不能传入一个负值
    :var test: 一个无关的测试量

function 指令后书写函数原型, 应当处于同一行中.
:param xxx: 描述一个参数的名称 xxx.
:type xxx: 描述参数 xxx 的类型.
:param type name: 同时描述一个参数的类型与名称.
:return: 描述返回值.
:rtype: 描述返回值的类型.
:raise xxx: 描述抛出的异常.
:var yyy: 描述用到的一个变量.

并且可以通过 getDate() 来创建一个指向该函数的链接:

并且可以用过 :func:`getDate` 来创建一个指向该函数的链接

类¶

class Clock(speed=0.0)¶

gamma()¶

求解 \(\gamma\) 因子

\[\gamma = \frac{1}{ \sqrt{ 1 - \frac{v^2}{c^2} } }\]

返回:	gamma
返回类型:	float

speed(v)¶

设置该钟表相对观察者的速度.

参数:	v (float) – 速度, 单位 m/s

position¶: 该物体相对观察者的位置 (float x, float y).

方法使用 method , 可接受的修饰和函数一致.

类/方法/属性, 可以使用 Clock, gamma(), position 来创建链接:

.. class:: Clock(speed=0.0)

    .. method:: gamma()

        求解 :math:`\gamma` 因子

        .. math:: \gamma = \frac{1}{ \sqrt{ 1 - \frac{v^2}{c^2} } }

        :return: gamma
        :rtype: float

    .. method:: speed(v)

        设置该钟表相对观察者的速度.

        :param float v: 速度, 单位 m/s

    .. attribute:: position

        该物体相对观察者的位置 ``(float x, float y)``.

类/方法/属性, 可以使用 :class:`Clock`, :meth:`gamma`, :attr:`position` 来创建链接

数据¶

用于解释程序中出现的一些重要数据, 比如全局变量/常量.

NULL¶: 0

并且, 使用 NULL 来创建一个指向该块的链接:

.. data:: NULL

    ``0``

并且, 使用 :data:`NULL` 来创建一个指向该块的链接