Sphinx中角色和指令语法

4.1. Sphinx中角色和指令语法#

rst使用directive和role进行特殊操作。

4.1.1. 角色#

备注

Sphin中，角色的说明为： Sphinx uses interpreted text roles to insert semantic markup into documents.

role的格式为：

:role名: 内容

角色包括：

  • 交叉引用： :any: ， :doc: ， :download: ， :envvar: ， :keyword: ， :numref: ， :option: ， :ref: ， :term: ， :token: 。

  • 行内高亮： :code: 。

  • 数学表达： :math: ， :eq: 。

  • 其他语义角色： :abbr: ， :command: ， :dfn: ， :file: ， :guilabel: ， :kbd: ， :mailheader: ， :makevar: ， :manpage: ， :menuselection: ， :mimetype: ， :newsgroup: ， :program: ， :regexp: ， :samp: ， :pep: ， :rfc: 。

Sphinx中的点位符也是角色，但使用的语法相对特殊，包括： |release| ， |version| ， |today| ， |translation progress| 。

4.1.2. 指令#

指令（Directives）是reStructureText的扩展机制。 可以在不增加新语法的情况下，增加新的结构性支持(a way of adding support for new constructs)。

指令由三部分组成，格式为：

.. directive-type:: directive-block
    :参数:
    :参数:

其中指令类型（directive-type）指明指令的类型，指令内容体又由三部分组成

  • 指令作用对象Directive arguments：指明该指令针对哪个对象作用

  • 指令选项参数Directive options：该指令的可选参数（可选），是一个参数列表

  • 指令内容说明Directive content：说明文档（可选）

比如插入一个图片

.. figure:: 图片名.png  # 这里是指令作用对象
    :scale: 50     # 这里是指令参数
        :width: 100

        这是一个图片   # 这里是说明

已在 reference reStructuredText parser 中实现的指令。

通用指令选项参数

:class:

得到

:name:

为指令设置名称(可用于简化别名链接)

 
.. image:: build.png
   :name: my pic
与下列方式等价
.. _my pic

.. image:: build.png

Sphinx支持的指令：

  • 目录： .. toctree:: ，

  • 段落级别标识，如 Admonitions, messages, and warnings， 包括： .. attention:: ， .. caution:: ， .. danger:: ， .. error:: ， .. hint:: ， .. important:: ， .. note:: ， .. tip:: ， .. warning:: ， .. admonition:: title ， .. seealso:: 。

  • 版本变动指令： .. versionadded:: version [brief explanation] ， .. versionchanged:: version [brief explanation] ， .. deprecated:: version [brief explanation] ， .. versionremoved:: version [brief explanation] 。

  • 呈现方式（Presentational）： .. rubric:: title ， .. centered: ， .. hlist:: 。

  • 代码高亮指令： .. highlight:: language ， .. code-block:: [language] ， .. sourcecode:: [language] ， .. code:: [language] ， .. literalinclude:: filename 。

  • 词汇表： .. glossary:: 。

  • 元信息标识 （Meta-information markup）： .. sectionauthor:: name <email> ， .. codeauthor:: name <email> 。

  • 索引生成标识 ： .. index:: <entries> ， 这个得配合使用 :index: 。

  • 基于标签的内容包含指令： .. only:: <expression> 。 This directive is designed to control only content of document. It could not control sections, labels and so on.

  • 表格指令：

  • 数学指令 ：

还有一类也属于指令，但语法不一样。 在Sphnx中用作特殊文档： genindex ， modindex ， search ， 以及以 _ 开头的名称。 Sphinx 使用这些保留名称用以特殊作用，创建文件时不要使用这些名称。

4.1.3. 元信息标记#

.. sectionauthor:: name <email>

标识当前部分的作者。该论点应包括作者的姓名, 以便它可用于演示文稿和电子邮件地址。地址的域名部分应为小写。例:

.. sectionauthor:: Guido van Rossum <guido@python.org>

默认情况下, 此标记不会以任何方式反映在输出中(它有助于跟踪贡献), 但您可以将配置值 show_authors 设置为 True 以使它们生成一个段落输出。

.. codeauthor:: name <email>

codeauthor 指令, 可以多次出现, 命名所描述代码的作者, 就像 sectionauthor 命名一篇文档的作者。 如果 show_authors 配置值为 True , 它也只产生输出。

目录