reStructuredText简明语法

内容简介：reStructuredText简明语法

https://github.com/xunxuny/zh-sphinx-doc/blob/master/rest.rst

段落

内联标记

标准的reST 内联标记相当简单:

• 星号: *text* 是强调 (斜体),
• 双星号: **text** 重点强调 (加粗),
• 反引号: text 代码样式.

星号及反引号在文本中容易与内联标记符号混淆，可使用反斜杠符号转义.

标记需注意的一些限制:

• 不能相互嵌套,
• 内容前后不能由空白: 这样写 * text* 是错误的,
• 如果内容需要特殊字符分隔. 使用反斜杠转义，如: thisis\ *one*\ word .

这些限制在未来版本可能会被改善.

标准reST 提供以下规则:

详情请查看 inline-markup .

列表与引用

* 这是一个项目符号列表.
* 它有两项，
  第二项使用两行.

1. 这是个有序列表.
2. 也有两项.

#. 是个有序列表.
#. 也有两项.

列表可以嵌套，但是需跟父列表使用空行分隔 :

* 这是
* 一个列表

  * 嵌套列表
  * 子项

* 父列表继续

定义列表 (ref <definition-lists>) :

术语 (term 文本开头行)
   定义术语，必须缩进

   可以有多段组成

下一术语（term）
   描述.

一行仅能写一个术语.

引用段落 (ref <block-quotes>) 仅使用缩进（相对于周围段落）创建.

行模块 (ref <line-blocks>) 可以这样分隔 :

| 这些行
| 在源文件里
| 被分隔的一模一样.

还有其他有用的模块:

• 字段列表 (ref <field-lists>)
• 选项列表(ref <option-lists>)
• 字面引用模块 (ref <quoted-literal-blocks>)
• 文档测试模块 (ref <doctest-blocks>)

源代码

这是一段正常文本. 下一段是代码文字::

   它不需要特别处理，仅是
   缩进就可以了.

   它可以有多行.

再是正常的文本段.

这个 :: 标记很优雅:

• 如果作为独立段落存在,则整段都不会出现在文档里.
• 如果前面有空白，则标记被移除.
• 如果前面是非空白，则标记被一个冒号取代.

因此上面的例子第一段文字将变为”下一段是代码文字:”.

表格

+------------------------+------------+----------+----------+
| 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             | ...        | ...      |          |
+------------------------+------------+----------+----------+

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

超链接

外部链接

可以把链接和标签分开 (ref<hyperlink-targets>), 如下:

段落里包含 `a link`_.

.. _a link: http://example.com/

内部链接

内部链接是Sphinx特定的reST角色, 查看章节 ref-role.

章节

章节的标题 (ref <sections>) 在双上划线符号之间（或为下划线）,并且符号的长度不能小于文本的长度:

=================
This is a heading
=================

通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:

• # 及上划线表示部分
• * 及上划线表示章节
• = , 小章节
• - , 子章节
• ^ , 子章节的子章节
• " , 段落

当然也可以标记（查看 reST 文档),定义章节的层次，但是需要注意输出格式(HTML, LaTeX)所支持的层次深度 .

显式标记

显式标记”Explicit markup” (ref <explicit-markup-blocks>)用在那些需做特殊处理的reST结构中, 如尾注，突出段落，评论，通用指令.

指令

指令 (ref <directives>) 是显式标记最常用的模块. 也是reST的扩展规则, 在 Sphinx 经常被用到.

文档 工具 支持以下指令:

• 警告: attention, caution, danger, error, hint, important, note, tip,
  warning 及通用标记 admonition. (大多数模式仅支持 “note” 及
  “warning” )
• 图像:
  • image (详情可看下面的 图像_ )
  • figure (有标题及可选说明的图像)
• 额外的主体元素:
  • contents <table-of-contents> (本地，仅是当前文件的内容表格)
  • container (自定义容器，用来生成HTML的 <div> )
  • rubric (和文档章节无关的标题)
  • topic, sidebar (高亮显示的主体元素)
  • parsed-literal (支持内联标记的斜体模块)
  • epigraph (可选属性行的摘要模块)
  • highlights, pull-quote (有自己的类属性的摘要模块)
  • compound ( 复合段落)
• 专用表格:
  • table (有标题的表格)
  • csv-table (CSV自动生成表格)
  • list-table (列表生成的表格)
• 专用指令:
  • raw (包含原始格式的标记)
  • include (包含reStructuredText标记的文件) –
    在Sphinx中,如果包含绝对文件路径，指令会以源目录地址做为参照
  • class (将类属性指派给下一个元素) [^1]
• HTML 特性:
  • meta (生成HTML <meta> 标签)
  • title (覆盖文档标题)

• 影响标记:

  • default-role (设置新的默认角色)
  • role (创建新的角色)

  如果仅有一个文件，最好使用 default_role.

设置不使用指令 sectnum, header 及 footer.

Sphinx 新增指令可查阅 sphinxmarkup.

指令有名字，参数，选项及内容组成.(记住这些，在下面一小节中自定义指令里会用到).来看一个例子:

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   返回用户输入的一行文本.

指令的内容在隔开一个空行后，与指令有一样缩进.

图像

reST 支持图像指令 (ref <image>), 如下:

.. image:: gnu.png
   (选项)

Sphinx 延伸了标准的文档化行为，只需在后面加星号:

.. image:: gnu.*

尾注

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] 第一条尾注的文本.
.. [#f2] 第二条尾注的文本.

你也可以使用数字尾注 ( [1]_ ) 或使用自动 排序 的( [#]_ ).

引用

支持标准的reST 引用 (ref <citations>) , 且新增了”global”特性,所有参考文献不受所在文件的限制. 如:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] 参考文献, 书,URL 等.

引用的使用同尾注很相近，但是它们没有数字标签或以 # 开始.

替换

.. |name| replace:: replacement *text*

或者:

.. |caution| image:: warning.png
             :alt: Warning!

详情查看reST reference for substitutions <substitution-definitions> .

Sphinx 定义了一些默认的替换, 请查看 default-substitutions.

评论

有明确标记块但又不是有效的结构标记的标记 (像上面的尾注）都被视为评论(ref <comments>). 例如:

.. 这是一个评论.

可以通过缩进产生多行评论:

..
   这整个缩进块都是
   一个评论.

   仍是一个评论.

源编码

在reST使用Unicode字符可以容易的包含特殊字符如破折号，版权标志. Sphinx默认源文件使用UTF-8 编码; 你可以通过 source_encoding 的配置值改变编码.

常见问题

具体使用中可能会遇到一些问题:

• 内联标记的分离
  如上面所讲，内联标记需与周围的文本使用空格分隔, 内联标记内部则使用反斜线转义空格.
  查看详情:

  the

  reference

  .
• 内联标记不能嵌套 像这样写 *see :func:`foo`* 是不允许的.

Footnotes

[^1]: 当默认主域里包含指令 :rstclass , 这个指令将被隐藏 因此, Sphinx使用:rstrst-class.

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

• Swift语法快速入门（一）之 Swift基础语法
• 在ES6中使用扩展语法有什么好处？它与rest语法有什么不同？
• Python 基础语法
• go语法
• JPQL 语言语法
• Golang：语法

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。