reStructuredText¶
reStructuredText 标记语言，相对 Markdown 来说，在写书方面更有优势:
使用
sphnix能够自动生成目录和索引文件，方便查询和检索；有大量漂亮的HTML书籍主题模版，可为书籍轻松换肤（类似
Wordpress的网站模版）；对于参考手册类书籍的编写在语法上更为便利（
python官方帮助文档的使用者）；
# 下划线及上划线表示 部分
* 划线及上划线表示 章节
= 下划线表示 小章节
- 下划线表示 子章节
^ 下划线表示 子章节的子章节
" 下划线表示 段落
*emphasis*
**emphasis**
`interpreted text`
``inline literal``
:sub:`xxx`
:sup:`xxx`
:guilabel:`Action`
:kbd:`Ctrl+Shift`
:menuselection:`A-->B-->C`
列表¶
- 无序
1. 有序
#. 自动编号
定义列表¶
术语的定义
term
术语定义必须缩进
可以包含多个段落
next term
术语描述
分块
| These lines are
| broken exactly like in
| the source file.
源代码¶
注意大多数时候，空格代替一个换行符。所有有些时候换行是必要的。比如 .. code-block:: 下面接了一句普通的话。块和半句是不能放在一起的。
标记符号 :: 紧接一空白行（这个空行是必要的）, 然后紧跟代码, 整个代码文本块必须缩进 这里的如:
::
some codes
some codes
some codes
此行上面的空行也是必要的
显式标记块的第一行是以 .. 开始，接着是紧随着空格，被结束于同样层级缩进的下一段落。（显式标记和正常的段落之间需要有一个空行。当你写它的时候，可能听起来有点复杂，但它是直观的。）
高级的代码高亮功能
此行下面的空行也是必要的
.. code-block:: python
:caption: Code Blocks can have captions.
:linenos:
:emphasize-lines: 3,5
def some_function():
interesting = False
print 'This line is highlighted.'
print 'This one is not...'
print '...but this one is.'
快速定义代码块
.. highlight:: sh
此指令后如下的“::”定义的块都会以 sh 语法进行高亮，直到遇到下一条 highlight 指令。
::
# 此命令在主机执行
sudo apt install python
echo "helloworld,this is a script test!"
literalinclude 直接嵌入本地文件并高亮
.. literalinclude:: ../../base_code/hello.c
:caption: ../../base_code/hello.c
:language: c
:emphasize-lines: 5,7-12
:linenos:
:name: hello.c
嵌入文件的某部分
.. literalinclude:: ../../base_code/hello.c
:caption: ../../base_code/hello.c
:language: c
:linenos:
:lines: 1,3,5-8,20-
python 模块的include。他有选择性的选取 timer.start
.. literalinclude:: example.py
:pyobject: Timer.start
文件对比
.. literalinclude:: ../../base_code/hello.c
:diff: ../../base_code/hello_diff.c
表格¶
.. 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!"
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
.. table:: Grid Table Demo
:name: table-gridtable
+------------------------+----------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+==========+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+----------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+----------+----------+----------+
直接标记 (Explicit Markup)¶
.. 这是一个注释, 你只能在源码中看到我, 我不会被渲染出来.
注意：.. 与评论块不能有空格
..
这整个缩进块都是
一个注释.
你只能在源码中看到我们, 我们不会被渲染出来
仍是一个评论.
.. |image_name| image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: 对于不能显示图片的时候, 显示这些文字
:align: right
数学公式¶
注意：尽管 .. math:: 与公式之间可以不需要空行，但是仍然非常建议加上。
行内公式 :math:`\alpha > \beta` :
Display 公式:
.. math::
n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k
带标签公式:
.. math::
:label: This is a label
n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k
多行公式:
.. math::
(a + b)^2 = a^2 + 2ab + b^2
(a - b)^2 = a^2 - 2ab + b^2
对齐多行公式:
.. math::
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2
提示警告类¶
注意：尽管 .. something:: 之间不需要空行。
.. tip:: This is a tip
.. note:: This is a note
.. hint:: This is a hint
.. danger:: This is a danger
.. error:: This is an error
.. warning:: This is a warning
.. caution:: This is a caution
.. attention:: This is an attention
.. important:: This is an important
.. seealso:: This is seealso
超链接¶
This is a paragraph that contains `a link`_.
.. _a link: http://example.com/
内部链接¶
.. _figure-datangfurongyuan:
.. figure:: ../_static/figs/mkdocs/insertfigure.png
...
图片¶
Sphinx将会自动将图像文件拷贝到输出目录中（例如HTML格式输出，会拷贝到 _static 目录中。）
Sphinx扩展了标准的docutils的功能，允许文件扩展名为星号:
.. image:: gnu.png
(options)
.. image:: gnu.*
(options)
引用¶
引用文档¶
自定义引用文字
:doc:`引用本地的其它 rst 文档,rst 后缀要省略，如 about_us <../about_us>`
使用标题文字
:doc:`../about_us`
使用标签引用文档¶
:ref:`about_embedfire <about_embedfire>`
:ref:`about_embedfire`
引文¶
所有的文件可以使用所有的引文。
引文用法是类似的脚注的用法，但带标签不是数字，或以#开始。
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
脚注¶
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
下载¶
:download:`引用非 rst 的本地文档 <../requirements.txt>`.
html¶
.. raw:: html
<iframe src="//player.bilibili.com/player.html?aid=70961112&cid=122951107&page=1" crolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>
Sphinx标记结构¶
toctree¶
由于reST不便于多个文件相互关联或者分割文件到多个输出文件中，Sphinx通过使用自定义的指令（标识符）来处理构成文档的单个文件的关系，这同样使用与内容表。toctree 指令（标识符）就是核心要素。
推荐阅读：
几个重要的附加选项
:maxdepth:2 设置最大深度
:numbered: 自动编号
:name: 名字
:titlesonly: 仅显示在树中的文件的标题，而不是其他的同级别的标题
:glob: 通配符，这样写文件条目简单写
:reversed: 反向编号
:hidden: 隐藏，如果想要从toctree生成”sitemap”的话，这是非常有用的
特殊的文件名
genindex 总索引
modindex Python模块索引
search 搜索页
案例
所有这些文件的内容表被加入，最大的深度为2，这意味着一个嵌套标题。在这些文件中的
toctree指令（标识符）也会被考虑到（识别）。All about strings <strings>，index.rst中显示All about strings，点击时索引到string.rst（可以换成<https://www,baidu.com>）glob使得docdir2/*和*的星号能被替换
.. toctree::
:glob:
:reversed:
:numbered:
:maxdepth:2
:caption: test
intro
docdir2/*
*
All about strings <strings>
Go to Baidu <https://www,baidu.com>
内联标记 Inline markup¶
Sphinx使用经过解释的 text role 将语义标记插入文档。
交叉引用语法¶
:role:`target`
使用下面的可以链接
:role:`title <target>`
下面不会创建链接
:role:`!target`
下面创建的是路径
:role:`~target`
交叉引用 objects¶
python 的交叉引用
:py:mod:
:py:func:
:py:data:
:py:const:
:py:class:
:py:meth:
:py:attr:
:py:exc:
:py:obj:
替换¶
|release|
|version|
|today|
段落级标记¶
这些指令（标识符）创建简短的段落，可用于内部信息的单位以及普通的文本
.. note:: 这是note
.. note::
这也是 note，推荐这么写。
.. warning:: 这是warning
.. versionadded:: 2.5
The *spam* parameter.
.. versionchanged:: 2.6
The reason why you changed the version.
.. deprecated:: 1.0
说明了什么场合功能不推荐使用。
Use :func:`spam` instead.
.. seealso:: 这是seealso
.. rubric:: title
该指令（标识符）创建一个段落，标题，不使用节点创建一个表的内容。
.. centered:: LICENSE AGREEMENT
创建一个居中粗体显示的文本行。
.. hlist::
:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally