Robot Framework 新版教程 - 库文档工具（Libdoc）

(Robot Framework 7.x 教程, Part 22)

库文档工具（Libdoc）

Libdoc 是 Robot Framework 的内置工具，可以为 Robot Framework 库和资源文件生成文档。它既可以生成供人类阅读的 HTML 文档，也可以生成 XML 和 JSON 格式的机器可读 spec 文件。Libdoc 还提供了一些特殊命令，可以在控制台上显示库或资源文件的信息。

可以为以下内容创建文档：

• 使用普通静态库 API 实现的库，
• 使用动态 API 的库，包括 remote 库，
• 资源文件，
• 套件文件，以及
• 套件初始化文件。

此外，还可以将 Libdoc 之前生成的 XML 和 JSON spec 文件作为输入。

对套件文件和套件初始化文件生成文档的支持是 Robot Framework 6.0 的新功能。

一般用法

命令概要

libdoc [options] library_or_resource output_file
libdoc [options] library_or_resource list|show|version [names]

选项

-f, --format <html|xml|json|libspec>
                         指定生成供人类阅读的 HTML 输出还是 XML 或 JSON 格式的
                         机器可读 spec 文件。libspec 格式表示将文档转换为 HTML 的
                         XML spec。默认格式根据输出文件的扩展名决定。
-s, --specdocformat <raw|html>
                         指定 XML 和 JSON spec 文件中使用的文档格式。raw 表示
                         保留原始文档格式，html 表示将文档转换为 HTML。默认情况下
                         XML spec 文件使用 raw，JSON spec 文件以及使用特殊的
                         libspec 格式时使用 html。
-F, --docformat <robot|html|text|rest>
                         指定源文档格式。可选值为 Robot Framework 的文档格式、
                         HTML、纯文本和 reStructuredText。默认值可以在测试库源代码中
                         指定，初始默认值为 robot。
--theme <dark|light|none>
                         使用深色或浅色 HTML 主题。如果不使用此选项，或者值为 none，
                         则根据浏览器配色方案选择主题。仅适用于 HTML 输出。
                         Robot Framework 6.0 新功能。
--language <lang>
                         设置文档中的默认语言。lang 必须是内置语言的代码，
                         包括 en 和 fi。Robot Framework 7.2 新功能。
-N, --name <newname>     设置被文档化的库或资源文件的名称。
-V, --version <newversion>  设置被文档化的库或资源文件的版本。
                         测试库的默认值在源代码中定义。
-P, --pythonpath <path>  额外的库和资源搜索路径，与运行测试时类似。
--quiet                  不在控制台打印生成的输出文件路径。
-h, --help               打印此帮助信息。

执行 Libdoc

运行 Libdoc 最简单的方式是使用作为常规安装一部分创建的 libdoc 命令：

libdoc ExampleLibrary ExampleLibrary.html

另一种方式是直接执行 robot.libdoc 模块。当你安装了多个 Python 版本并希望使用特定版本运行 Libdoc 时，这种方式尤其有用：

python -m robot.libdoc ExampleLibrary ExampleLibrary.html
python3.9 -m robot.libdoc ExampleLibrary ExampleLibrary.html

还有一种方式是将 robot.libdoc 模块作为脚本运行：

python path/to/robot/libdoc.py ExampleLibrary ExampleLibrary.html

独立的 libdoc 命令是 Robot Framework 4.0 的新功能。

指定库或资源文件

通过名称或路径指定 Python 库和动态库

当为使用 Python 实现或使用动态库 API 的库生成文档时，可以通过库名称或库源代码路径来指定：

libdoc ExampleLibrary ExampleLibrary.html
libdoc src/ExampleLibrary.py docs/ExampleLibrary.html

在前一种情况下，库通过模块搜索路径查找，其名称必须与在 Robot Framework 测试数据中导入库时使用的格式相同。

如果这些库在导入时需要参数，参数必须使用双冒号连接在库名称或路径之后，例如 MyLibrary::arg1::arg2。如果参数会改变库提供的关键字或以其他方式影响其文档，使用 --name 选项相应地更改库名称可能是个好主意。

通过路径指定资源文件

资源文件必须始终使用路径来指定：

libdoc example.resource example.html

如果路径不存在，资源文件也会像执行测试用例时一样从模块搜索路径中的所有目录中查找。

Libdoc spec 文件

之前生成的 Libdoc XML 或 JSON spec 文件也可以用作输入。前提是 spec 文件使用 *.xml、*.libspec 或 *.json 扩展名：

libdoc Example.xml Example.html
libdoc Example.libspec Example.html
libdoc Example.json Example.html

对 *.libspec 扩展名的支持是 Robot Framework 3.2 的新功能。

对 *.json 扩展名的支持是 Robot Framework 4.0 的新功能。

生成文档

Libdoc 可以生成 HTML（供人类阅读）和 XML 或 JSON（供工具使用）格式的文档。写入文档的文件作为库/资源名称或路径之后的第二个参数指定，默认情况下输出格式根据输出文件的扩展名决定。

Libdoc HTML 文档

大多数 Robot Framework 库使用 Libdoc 生成 HTML 格式的库文档。因此大多数使用过 Robot Framework 的人都熟悉这种格式。下面可以看到一个简单的示例，它是基于本节稍后的示例生成的。

HTML 文档以库的总体介绍开始，接着是关于导入时如何配置库的部分（如果适用），最后是所有关键字的快捷方式和关键字本身。右下角的放大镜图标可以打开关键字搜索对话框，也可以通过直接按 s 键打开。

如果输出文件扩展名为 *.html，Libdoc 会自动创建 HTML 文档。如果需要使用其他扩展名，可以通过 --format 选项显式指定格式。

从 Robot Framework 7.2 开始，可以通过 --language 选项对 HTML 文档中的静态文本进行本地化。

有关如何为本地化添加新语言的最新信息，请参阅项目仓库中 src/web/libdoc 目录下的 README.rst 文件。

libdoc OperatingSystem OperatingSystem.html
libdoc --name MyLibrary Remote::http://10.0.0.42:8270 MyLibrary.html
libdoc --format HTML test/resource.robot doc/resource.htm

Libdoc XML spec 文件

Libdoc 还可以生成 XML 格式的文档，适用于编辑器等外部工具。它包含与 HTML 格式相同的所有信息，但采用机器可读的格式。

XML spec 文件还包含库和关键字的源信息，使得库和每个关键字都可以有源路径（source 属性）和行号（lineno 属性）。源路径相对于 spec 文件生成的目录，因此如果 spec 文件被移动，路径将不再指向正确的文件。如果关键字的源路径与库的相同，则省略关键字的源路径；如果由于任何原因无法从库中获取源路径和行号，则两者都会被省略。

如果输出文件扩展名为 *.xml 或 *.libspec，Libdoc 会自动使用 XML 格式。当使用特殊的 *.libspec 扩展名时，Libdoc 会自动启用选项 -f XML -s HTML，这意味着创建一个将关键字文档转换为 HTML 的 XML 输出文件。如果需要，可以使用 --format 选项显式设置格式。

libdoc OperatingSystem OperatingSystem.xml
libdoc test/resource.robot doc/resource.libspec
libdoc --format xml MyLibrary MyLibrary.spec
libdoc --format xml -s html MyLibrary MyLibrary.xml

确切的 Libdoc spec 文件格式在 https://github.com/robotframework/robotframework/tree/master/doc/schema 处通过 XML schema（XSD）进行文档化。spec 文件格式可能会在 Robot Framework 主要版本之间发生变化。

为了让外部工具更容易知道如何解析特定的 spec 文件，spec 文件根元素有一个专门的 specversion 属性。它在 Robot Framework 3.2 中添加，值为 2，更早的 spec 文件可以视为版本 1。如果将来进行了更改，spec 版本将递增。Robot Framework 4.0 引入了新的 spec 版本 3，与之前的版本不兼容。

Robot Framework 3.2 中引入的 XML:HTML 格式已被 LIBSPEC 格式或选项组合 --format XML --specdocformat HTML 所取代。

包含源信息和 spec 版本是 Robot Framework 3.2 的新功能。

Libdoc JSON spec 文件

从 Robot Framework 4.0 开始，Libdoc 还可以生成 JSON 格式的文档，适用于编辑器或网页等外部工具。它包含与 HTML 格式相同的所有信息，但采用机器可读的格式。

与 XML spec 文件类似，JSON spec 文件包含所有信息，也可以用作 Libdoc 的输入。从该格式可以创建任何其他输出格式。默认情况下，JSON 输出文件中的库文档字符串会被转换为 HTML 格式。

确切的 JSON spec 文件格式在 https://github.com/robotframework/robotframework/tree/master/doc/schema 处通过 JSON schema 进行文档化。spec 文件格式可能会在 Robot Framework 主要版本之间发生变化。

在控制台查看信息

Libdoc 有三个特殊命令用于在控制台显示信息。这些命令用于替代输出文件名称，它们还可以接受额外的参数。

list

列出库/资源文件包含的关键字名称。可以通过传递可选的模式（pattern）作为参数来限制仅显示特定关键字。如果关键字名称包含给定的模式，则会被列出。

show

显示库/资源文件的文档。可以通过传递名称作为参数来限制仅显示特定关键字。如果关键字名称匹配任何给定的名称，则会被显示。特殊参数 intro 将仅显示库的介绍和导入部分。

version

显示库版本。

传递给 list 和 show 的可选模式不区分大小写和空格。两者都接受 * 和 ? 作为通配符。

示例：

libdoc Dialogs list
libdoc SeleniumLibrary list browser
libdoc Remote::10.0.0.42:8270 show
libdoc Dialogs show PauseExecution execute*
libdoc SeleniumLibrary show intro
libdoc SeleniumLibrary version

编写文档

本节讨论如何为使用静态库 API 的基于 Python 的测试库、动态库以及资源文件编写文档。创建测试库和资源文件在用户指南的其他地方有更详细的描述。

Python 库

使用静态库 API 的 Python 库的文档，直接以库类或模块的文档字符串（doc string）以及实现关键字的方法的文档字符串来编写。方法文档的第一行被视为关键字的简短文档（例如，在生成的 HTML 文档的链接中用作工具提示），因此应尽可能具有描述性，但不宜过长。

下面的简单示例说明了一般如何编写文档。基于此示例生成的 HTML 文档可以在上文中看到，本章末尾还有一个更长的示例。

src/SupportingTools/ExampleLibrary.py

如果你的库执行了一些不应在使用 Libdoc 时进行的初始化工作，你可以轻松检测 Robot Framework 是否正在运行。

有关 Python 文档字符串的更多信息，请参阅 PEP-257。

动态库

为了能够为动态库生成有意义的文档，库必须通过 get_keyword_arguments 和 get_keyword_documentation 方法（或它们的驼峰命名变体 getKeywordArguments 和 getKeywordDocumentation）返回关键字参数名称和文档。库还可以通过向 get_keyword_documentation 方法传递特殊的 __intro__ 和 __init__ 值来支持通用库文档。

有关如何创建这些方法的更多信息，请参阅动态库 API 一节。

导入部分

关于如何导入库的独立部分是基于其初始化方法创建的。如果库有一个除 self 之外还接受参数的 __init__ 方法，则会显示其文档和参数。

class TestLibrary:

    def __init__(self, mode='default')
        """创建新的 TestLibrary。`mode` 参数用于确定模式。"""
        self.mode = mode

    def some_keyword(self, arg):
        """基于给定的 `arg` 执行某些操作。

        执行的具体操作取决于 `importing` 库时指定的 `mode`。
        """
        if self.mode == 'secret':
             # ...

资源文件文档

资源文件中的关键字可以使用 [Documentation] 设置项提供文档，此文档也会被 Libdoc 使用。文档的第一行（直到第一个隐式换行或显式的 \n）被视为简短文档，与测试库类似。

资源文件本身也可以在 Settings 部分使用 Documentation 来为整个资源文件编写文档。

资源文件中的变量无法被文档化。

*** Settings ***
Documentation    用于演示目的的资源文件。
...              此资源文件仅用于示例，不执行任何有用的操作。

*** Keywords ***
My Keyword
    [Documentation]   不执行任何操作
    No Operation

Your Keyword
    [Arguments]  ${arg}
    [Documentation]   接受一个参数并且对其*不做任何操作*。
    ...
    ...    Examples:
    ...    | Your Keyword | xxx |
    ...    | Your Keyword | yyy |
    No Operation

文档语法

Libdoc 支持 Robot Framework 自有的文档语法、HTML、纯文本和 reStructuredText 格式的文档。使用的格式可以通过库源代码中的 ROBOT_LIBRARY_DOC_FORMAT 属性指定，或者通过命令行的 --docformat (-F) 选项指定。两种情况下，可选的不区分大小写的值为 ROBOT（默认）、HTML、TEXT 和 reST。

Robot Framework 自有的文档格式是默认的，也是一般推荐使用的格式。其他格式在测试库中使用已有代码和已有文档时特别有用。

Robot Framework 文档语法

Robot Framework 文档语法中最重要的特性包括：使用 *bold* 和 _italic_ 进行格式化、自定义链接和 URL 自动转换为链接，以及使用管道字符简单地创建表格和预格式化文本块（对示例很有用）。如果文档较长，对节标题的支持也很方便。

下面的示例展示了一些最重要的格式化特性。注意，由于这是默认格式，因此无需使用 ROBOT_LIBRARY_DOC_FORMAT 属性，也无需从命令行指定格式。

"""Robot Framework 格式的示例库。

- 使用 *bold* 和 _italic_ 格式化。
- 像 http://example.com 这样的 URL 会自动转换为链接。
- 支持自定义链接如 [http://robotframework.org|Robot Framework]。
- 可以链接到 `My Keyword`。
"""

def my_keyword():
    """这里没有更多内容了。"""

自动创建目录

对于较大的库，在库介绍中添加目录通常很有用。使用 Robot Framework 文档格式时，可以通过在单独一行中添加特殊的 %TOC% 标记来自动完成。目录基于介绍中使用的顶级节标题（例如 = Section =）创建。除了这些标题外，目录还会获得指向自动创建的快捷方式和关键字部分的链接，以及（如果适用的话）导入和标签部分的链接。

"""演示目录生成的示例库。

%TOC% 标记仅创建实际的目录，可能的标题或其他说明需要像下面这样单独添加。

== Table of contents ==

%TOC%

= Section title =

顶级节标题会被自动添加到目录中。

= Second section =

== Sub section ==

子节标题不会被添加到目录中。
"""

def my_keyword():
    """这里没有更多内容了。"""

自动目录生成是 Robot Framework 3.2 的新功能。

HTML 文档语法

使用 HTML 格式时，你可以使用几乎任何语法相当自由地创建文档。主要缺点是 HTML 标记对人类不太友好，这可能使源代码中的文档难以维护和阅读。HTML 格式的文档会被 Libdoc 直接使用，不做任何转换或转义。但是支持使用 `My Keyword` 这样的语法进行关键字链接。

下面的示例包含与前一个示例相同的格式化示例。现在必须使用 ROBOT_LIBRARY_DOC_FORMAT 属性，或者从命令行指定格式如 --docformat HTML。

"""HTML 格式的示例库。

<ul>
  <li>使用 <b>bold</b> 和 <i>italic</i> 格式化。
  <li>URL 不会自动转换为链接。
  <li>支持自定义链接如 <a href="http://www.w3.org/html">HTML</a>。
  <li>可以链接到 `My Keyword`。
</ul>
"""
ROBOT_LIBRARY_DOC_FORMAT = 'HTML'

def my_keyword():
    """这里没有更多内容了。"""

纯文本文档语法

使用纯文本格式时，Libdoc 会原样使用文档。除了缩进之外，换行和其他空白都会保留，HTML 特殊字符（<>&）会被转义。唯一进行的格式化是将 URL 转换为可点击的链接以及支持使用 `My Keyword` 的内部链接。

"""纯文本格式的示例库。

- 不支持格式化。
- 像 http://example.com 这样的 URL 会转换为链接。
- 不支持自定义链接。
- 可以链接到 `My Keyword`。
"""
ROBOT_LIBRARY_DOC_FORMAT = 'text'

def my_keyword():
    """这里没有更多内容了。"""

reStructuredText 文档语法

reStructuredText 是一种简单而强大的标记语法，广泛用于 Python 项目（包括本用户指南）和其他地方。主要限制是需要安装 docutils 模块才能使用它生成文档。由于反引号字符在 reStructuredText 中有特殊含义，链接到关键字需要将其转义为 \`My Keyword\`。

reStructuredText 支持的一个不错的特性是能够标记可以进行语法高亮的代码块。语法高亮需要额外的 Pygments 模块，并支持 Pygments 支持的所有语言。

"""reStructuredText 格式的示例库。

- 使用 **bold** 和 *italic* 格式化。
- 像 http://example.com 这样的 URL 会转换为链接。
- 支持自定义链接如 reStructuredText__。
- 可以链接到 \`My Keyword\`，但需要转义反引号。

__ http://docutils.sourceforge.net

.. code:: robotframework

    *** Test Cases ***
    Example
        My keyword    # 这不是很酷吗!!?!!?!1!!
"""
ROBOT_LIBRARY_DOC_FORMAT = 'reST'

def my_keyword():
    """这里没有更多内容了。"""

内部链接

Libdoc 支持在文档中链接到关键字和不同的节。链接通过用反引号字符包围目标名称来完成，如 `target`。目标名称不区分大小写，可能的目标在后续各节中解释。

如果找不到链接目标，不会有错误或警告，Libdoc 只会将文本格式化为斜体。之前建议在引用关键字参数时使用这种格式，但这样做有问题，因为它可能会意外创建内部链接。现在建议使用双反引号的内联代码样式，如 argument 。旧的单反引号格式将来甚至可能被移除，转而在找不到链接目标时给出错误。

除了以下各节中的示例外，内部链接和参数格式化在本章末尾的更长示例中也有展示。

链接到关键字

库中的所有关键字会自动创建链接目标，可以使用 `Keyword Name` 语法进行链接。下面的示例进行了说明，其中两个关键字互相链接。

def keyword(log_level="INFO"):
    """执行某些操作并使用给定的级别记录输出。

    log level 的有效值为 "INFO"（默认）、"DEBUG" 和 "TRACE"。

    另请参阅 `Another Keyword`。
    """
    # ...

def another_keyword(argument, log_level="INFO"):
    """使用给定的参数执行某些操作并记录输出。

    有关有效日志级别的信息，请参阅 `Keyword`。
    """
    # ...

使用 reStructuredText 文档语法时，反引号必须转义为 \`Keyword Name\`。

链接到自动生成的节

Libdoc 生成的文档始终包含库整体介绍和关键字部分。如果库本身接受参数，还会有单独的导入部分。如果任何关键字有标签（tag），概览中还会显示标签选择器。

所有这些节都可以作为链接目标，可能的目标名称在下表中列出。下一节的示例展示了如何使用这些目标。

节	目标
Introduction	`introduction` 和 `library introduction`
Importing	`importing` 和 `library importing`
Keywords	`keywords`

在 Robot Framework 4.0 之前还有标签和快捷方式部分。在 Robot Framework 4.0 中，这些已被概览菜单取代。这意味着之前链接到快捷方式或标签部分的链接将不再有效。

链接到自定义节

Robot Framework 的文档语法支持自定义节标题，在库或资源文件介绍中使用的标题会自动创建链接目标。下面的示例说明了如何链接到自动节和自定义节：

"""用于 Libdoc 演示目的的库。

此库不执行任何有用的操作。

= My section  =

不过，我们在文档中确实有一个自定义节。
"""

def keyword():
    """不执行任何操作。

    有关更多信息请参阅 `introduction`，并查看 `My section` 以测试
    链接到自定义节是如何工作的。
    """
    pass

链接到自定义节仅在使用 Robot Framework 文档语法时有效。

参数表示

Libdoc 会自动显示关键字参数的信息。

包含的信息

无论关键字是在库中还是在资源文件中实现的，以下信息都会显示：

• 参数名称。用户关键字参数显示时不带 ${} 装饰，使参数在不同来源的关键字中看起来一致。
• 标记参数是仅限位置参数（positional-only）、仅限命名参数（named-only）、自由位置参数（free positional）、自由命名参数（free named）还是可以按位置或名称传递的普通参数。
• 可能的默认值。显示为 = 42。
• 可能的类型。显示为 <int>。可以是指向类型文档的链接，如下一节所述。

在关键字文档中引用参数时，建议使用双反引号的内联代码样式，如 argument 。

自动列出类型文档

如上所述，Libdoc 在列出参数时会自动显示可能的类型信息。如果类型是基于 Enum 或 TypedDict 的自定义类型、类型被自动转换，或者类型有自定义转换器，则该类型本身也会被单独列出以显示更多信息。当这些类型在参数中使用时，类型名称也会成为指向类型信息的链接。

所有列出的数据类型都会显示可能的类型文档以及支持哪些参数类型。除此之外，基于 Enum 的类型会列出可用的成员，基于 TypedDict 的类型会显示字典结构。

自动列出基于 Enum 和 TypedDict 的类型是 Robot Framework 4.0 的新功能。列出其他类型是 Robot Framework 5.0 的新功能。

Libdoc 示例

以下示例展示了如何使用最重要的文档格式化功能、内部链接等。点击这里可以查看生成的文档。

src/SupportingTools/LoggingLibrary.py

所有标准库都有由 Libdoc 生成的文档，它们的文档（和源代码）可以作为更实际的示例。