Home » Misc » reStructuredText 文档写作规范
  • 30
  • 09月

reStructuredText 文档写作规范

Post by digwtx at 2014. Category: Misc.

本规范主要适用于中小型文档，文档标题 6 级以内（ H1 ~ H6 ）。一般来说，单 个文件 3 级标题已经足够了。

1   章节标题

注解

标题上下方的符号数量必须与标题长度相同或者更多。

文档标题:

============
文档标题
============

一级标题:

一级标题
========

二级标题:

二级标题
--------

三级标题:

三级标题
~~~~~~~~

四级标题:

四级标题
`````````

五级标题:

五级标题
^^^^^^^^

六级标题:

六级标题
++++++++

章节自动编号，在 contents 指令下行追加 sectnum 指令，变成这样：

.. contents::
.. sectnum::

2   链接

2.1   外部链接

无名链接:

More detailed documentation can be viewed in the `Docutils' documentation`__.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#id48

注解

无名链接是具有作用域的，使用时要特别小心，以免产生混乱。

有名链接:

Slackware_ Linux_

.. _Slackware: http://www.slackware.com
.. _Linux: https://kernel.org

2.2   内部链接

锚点定义:

.. _database:

引用锚点:

`database`_

3   源代码

案例 1:

this is some code::

    from flask import Flask
    app = Flask(__name__)

案例 2:

.. sourcecode:: flask

    from flask import Flask
    app = Flask(__name__)

注解

sourcecode 使用 Pygments 高亮代码。

4   表格

简单表格：

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

5   列表

5.1   无序列表

- baidu
- google
- 360

5.2   顺序列表

1. baidu
#. google
#. 360

注解

# 可用于代替数字，它会自动编号。

5.3   定义列表

定义描述的缩进约定为 4 个空格。

term (up to a line of text)
    Definition of the term, which must be indented

    and can even consist of multiple paragraphs

next term
    Description.

5.4   行块元素

行块元素是防止行被破坏的方式（保留行原样的方式）:

| These lines are
| broken exactly like in
| the source file.

6   行内标记

注：因为找不到合适的词语来翻译 role ，所以没有翻译！

标准的行内标记相当简单：使用

  • 单星号： *text* 强调 (斜体),
  • 双星号： **text** 重点强调 (粗体)，以及
  • 反引号： ``text`` 代码示例。

如果星号或反引号出现在文本会对行内标记分隔符引起混淆，他们必须用一个反斜杠 进行转义。

注意行内标记一些限制:

  • 不能嵌套，
  • 文本不能以空格开始或者结束： * text* 是不正确的，
  • 必须由空格从周围的文本中分离出来。可以通过使用转义的空格来规避这个限制： thisisoneword 。

docutils以后的版本可能会取消上列出的这些限制。

reST也允许自定义“文本解释role”，这就意味着所包含的文本应以一种特定的方式 解释。Sphinx用它提供了语义标记和交叉引用的标识符。一般的语法格式是 :rolename:`content` 。

标准的reST提供了如下些roles：

  • emphasis – 来替代 *emphasis*
  • strong – 代替 **strong**
  • literal – 代替 ``literal``
  • subscript – 下标文本
  • superscript – 上标文本
  • title-reference – 书，期刊，以及其他材料的标题

7   引用文字

这里是指大段的文字引用。换个说法，就是 HTML 的 blockquote 标签。

正常段落缩进 4 个空格就可以实现引用的效果。

注解

这里约定缩进为 4 个空格。

这是一段。

这是第二段，下面引用点文字：

    段落可以缩进，通常用来表达引用的文字。

    这两段就是引用的文字了。

来，这里是第三段了。

下面是带属性的文字引用，翻译过来，就是 blockquote 多了个 class="epigraph" 属性。

.. epigraph::
   iweirwier

   weirwieriwer ``inweir`` weiriwerk sdfskd

   weirwieriwer

8   脚注

可以使用 [#name]_ 标注在脚注的位置，在文档的最后的 .. rubric:: Footnotes 后添加脚注的内容，像这样:

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

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

你也可以明确用数字标注脚注或者通过不指定 name 使用自动数字标记脚注( [#]_ )。

9   引文

Sphinx 支持标准 reST 引文，增加了所有引文是“全局的”的特性，即：所有的 文件可以使用所有的引文。这样使用它们:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引文用法是类似的脚注的用法，但带标签不是数字，或以 # 开始。

10   替换

reST 支持“替换”，这是文本和/或标记在文中 |name| 提到。它们是像脚注 用显著的标记块，像这样:

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

或者，这样:

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

细节请看 reST reference for substitutions。

11   在线编辑器