robotdoc-sphinxcontrib 0.11.0

简介

此软件包提供了一种Sphinx扩展，用于将Robot Framework测试套件、测试用例或用户关键字嵌入到Sphinx文档中，类似于autodoc Sphinx扩展。

何时使用？

请考虑不使用此软件包。

此软件包是在Robot Framework纯文本语法分析器（高亮显示支持）被实现并包含到Pygments（>= 1.6rc1）之前创建的。此软件包也是在Robot Framework的内置libdoc工具获得嵌入文档语法的ReST语法支持（>=1.7.5）以及Robot Framework获得新的ReST支持（>= 1.8.2）之前创建的。

如今，将Robot Framework代码（纯文本语法）嵌入到Sphinx文档中最简单的方法是简单地使用标准的 .. code-block:: robotframework 或使用 :download:-语法包含libdoc生成的HTML。然而，在某些边缘情况下，这可能是嵌入外部Robot示例到您的文档中最方便的方法。

用法

将 sphinxcontrib_robotdoc 添加到您的Sphinx配置（conf.py）的扩展列表中

extensions = [
    "sphinxcontrib_robotdoc",
]

使用以下自定义Docutils指令将测试用例和用户关键字嵌入到您的文档中

.. robot-tests:: Test case title or RegExp.*
   :source: my_package:tests/acceptance/my_suite.robot
   :tags: bugs, new

.. robot-keywords:: Keyword title or RegExp.*
   :source: my_package:tests/acceptance/my_suite.txt

两个指令（robot-tests 和 robot-keywords）都以正则表达式作为其主要选项（或 Docutils 术语中的 内容）来过滤从给定的 source-资源（或相对路径）中找到的嵌入测试用例或关键字。如果没有给出正则表达式，则将嵌入所有找到的测试或关键字（默认情况下如同使用 .*）。

提供给必需的 source-选项的路径必须是包资源（使用语法 package_name:resource/path/in/package）或从当前文档的相对路径。

测试用例指令（robot-tests）还接受一个可选的 tags 选项，它是可选的。它应包括要用于过滤要嵌入的测试的逗号分隔的标签列表。

两个指令都接受一个可选的 style-选项。当 style 设置为 expanded 时，输出将包括诸如表名和测试用例或关键字名称等标题。当 style 设置为 minimal 时，输出将仅包括目标文档字符串，而不包含任何 robot 语法。

请注意，从嵌入测试中找到的文档是通过 Docutils 解析的，作为目标文档的一部分。这与 Robot Framework 自身的文档工具不同，后者期望使用其自定义标记。

其他指令

robot-source 将嵌入带有语法高亮的完整测试套件或资源文件

.. robot-source::
   :source: my_package:tests/acceptance/my_suite.txt

robot-settings 将嵌入带有语法高亮的设置表（将文档作为 reStructuredText 解析）的测试套件或资源文件

.. robot-settings::
   :source: my_package:tests/acceptance/my_suite.txt

robot-variables 将嵌入带有语法高亮的变量表（将文档作为 reStructuredText 解析）的测试套件或资源文件

.. robot-variables::
   :source: my_package:tests/acceptance/my_suite.txt

此外，指令 robot-settings 和 robot-variables 还接受一个可选的 style-选项。当 style 设置为 expanded 时，输出将包括表名。

LaTeX 输出

LaTeX 输出基于 Pygments LatexFormatter，它需要将自定义样式定义注入到 LaTeX 文档的序言中。默认情况下会这样做，但当 Sphinx 的 latex_preamble 设置手动设置时，它应包括以下内容：

from pygments.formatters import LatexFormatter

latex_elements['latex_preamble'] = '''\
\usepackage{fancyvrb}
\usepackage{color}
''' + LatexFormatter().get_style_defs()

0.11.0 (2019-11-08)

• 修复逃逸字符错误 [Jasper Craeghs]

0.10.0 (2018-05-11)

• 将发布为通用 wheel [Asko Soukka]

• 针对较新 Sphinx 版本的更改 [Stein Heselmans]

0.9.1 (2017-05-31)

• 允许在 robot 文件的文档中包含制表符 [Stein Heselmans]

0.9.0 (2017-05-21)

• Python 3 支持 [Stein Heselmans]

0.8.0 (2015-10-09)

• 将逗号更改为双空格来分隔标签 [Asko Soukka]

0.7.3 (2014-06-13)

• 为测试用例、关键字标签添加扩展样式生成文档。 [Tomasz Kolek]

0.7.2 (2013-10-19)

• 修复以使用 Pygments 的 RobotFrameworkLexer。需要 Pygments >= 1.6rc1 [Asko Soukka]

• 删除对 robotframeworklexer 的依赖，因为它包含在 Pygments 中 [Asko Soukka]

0.7.0 (2013-10-16)

• 将指令重命名为 robot-source、robot-settings、robot-variables、robot-tests 和 robot-keywords，但保留旧指令以保持向后兼容。

0.6.0 (2013-09-28)

• 为关键字指令添加“minimal”样式，以显示不带其步骤定义的关键字 [Asko Soukka]

0.5.1 (2013-08-13)

• 修复设置部分中多行文档未完全包含的错误 [Pawel Sabat]

0.5.0 (2013-05-17)

• 添加使用 pkg_resources.resource_filename 方法解析“package:filename.robot”-路径的支持 [Asko Soukka]

• 修复源指令导致逃逸 HTML 标记的错误 [Asko Soukka]

0.4.1 (2013-03-24)

• 为 LaTeX 输出添加 Pygments 格式的输出 [修复 #4]

0.4.0 (2013-03-10)

• 添加新指令 robot_source、robot_settings 和 robot_variables

• 修复相对路径问题 [修复 #2]

• 重构并添加对 ForLoop-nodes 的支持 [修复 #1]

• 为 BDD-keywords 添加对齐

• 添加语法高亮

0.3.4 (2012-10-21)

• 修复了使用正确的标题样式来显示测试用例和关键词标题的问题。

0.3.3 (2012-10-21)

• 修复了一个错误，该错误导致空/缺失的标签选项无法正确解析。

0.3.2 (2012-10-20)

• 重构以使用 Docutils 的嵌套解析代替 publish_string（不再使用 lxml 并支持一些跨链接）。

0.3.1 (2012-10-18)

• 重构以使用 docutils.core.publish_string 解析测试/关键词文档（并将它们作为原始节点附加），而不是尝试将它们解析到 Sphinx 文档树中。

0.3.0 (2012-10-18)

• 添加了对测试和关键词文档中内联 rst 的支持。

• 添加了对 tags 的支持。

• 添加了作为 suite 选项别名的 source 选项作为测试中的备用选项。

• 添加了作为 suite 选项别名的 source 和 resource 选项作为关键词中的备用选项。

• 修复了从步骤中过滤注释行的功能。

0.2.0 (2012-10-14)

• 修复了节点适配器，使其返回节而不是主题。

0.1.1 (2012-10-14)

• 修复了关键词的资源文件解析。

0.1.0 (2012-10-14)

• 概念验证。