标准域

Added in version 1.0.

所谓的 “标准 “域收集所有不需要单独域的标记.它的指令和角色不带域名前缀.

标准域也是使用 add_object_type() API 添加的自定义对象描述所在的位置.

有一组指令可以用于记录命令行程序:

.. option:: name args, name args, ...

描述命令行参数或开关.选项参数名称应当用尖括号括起来.示例:

.. option:: dest_dir

   Destination directory.

.. option:: -m <module>, --module <module>

   Run a module as a script.

该指令将为给定的选项创建交叉引用目标,可以通过 option 进行引用(在示例中,您可以使用类似``:option:dest_dir``,``:option:-m``, 或``:option:`–module```的用法).

在 5.3 版本发生变更: 可以交叉引用包括一个选项值::option:`--module=foobar`,``:option:–module[=foobar]```或`--module foobar` .

使用 option_emphasise_placeholders 解析文本字面量的 “变量部分” (与 samp 角色类似).

cmdoption directive is a deprecated alias for the option directive.

.. confval:: name

描述文档代码或程序使用或定义的配置值或设置.可以通过 confval 引用.

:type: (text)

描述配置值的类型.这是可选的,如果指定,将被解释为reStructuredText.

:default: (text)

描述配置值的默认值.这是可选的,如果指定,将被解释为 reStructuredText.

示例:

.. confval:: the_answer
   :type: ``int`` (a *number*)
   :default: **42**

   This is a setting that controls the value of the answer.

将渲染如下:

the_answer
类型:
int (a number)
默认:
42

这是一个控制答案值的设置.

.. envvar:: name

描述被文档代码或程序使用或定义的环境变量.可通过 envvar 引用.

.. program:: name

py:currentmodule 类似,该指令不产生输出.相反,它用于通知 Sphinx 所有后续的 option 指令为名为 name 的程序文档选项.

如果您使用 :rst :dir:`program` ,则必须在 option 角色中按程序名称限定引用,因此如果您有以下情况

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r <revision>

   Specify the revision to work upon.

那么``:option:rm -r```将指代第一个选项,而`:option:`svn -r```将指代第二个选项.

如果将 None 传递给参数,该指令将重置当前程序名称.

程序名称可以包含空格(以便您想单独记录子命令,如 svn addsvn commit ).

Added in version 0.5.

还有一个非常通用的对象描述指令,它与任何领域都没有绑定:

.. describe:: text
.. object:: text

此指令生成与各领域提供的特定格式相同的格式,但不会创建索引条目或交叉引用目标.示例:

.. describe:: PAPER

   You can set this variable to select a paper size.