robotframework笔记25

library文档工具(Libdoc)

Libdoc是机器人框架内置的工具生成的关键字的文档 测试库和资源文件的HTML和XML格式。 前 格式适用于人类,后者 骑 和其他 工具。 Libdoc显示库或也有几个特殊的命令 在控制台上资源信息。

可以创建文档:

• 测试库实现 Python 或 Java 使用正常 静态库API,
• 测试库使用 动态API ,包括远程库
• 资源文件 。

另外可以使用Libdoc创建的XML规范 作为输入。

一般使用

剧情简介

python -m robot.libdoc [options] library_or_resource output_file
python -m robot.libdoc [options] library_or_resource list|show|version [names]

选项

- f , - - -格式 < html | xml >
	指定是否要生成HTML或XML输出。 如果不使用此选项,格式 扩展的输出文件。
- f , ——docformat <机器人其他html文本| | | >
	指定源文件的格式。 可能的 值是机器人框架的文档格式, HTML、文本和恰好。 默认值 可以指定在测试库源代码和 初始默认值 机器人 。 2.7.5新机器人框架。
- n , ——名字 <新名称>
	集的名字记录库或资源。
- v , ——版本 <新版本>
	集的版本库或记录 资源。 测试库的默认值 从源代码 。
- p , ——pythonpath环境 <路径>
	额外的位置搜索库 和资源同样时 运行测试 。
- e , ——逃避 <什么:>
	转义字符的问题在控制台。 什么 角色的名字逃脱吗 和 与 是字符串来逃避它。 在列出可用的逃 ——帮助 输出。
- h ,——帮助	打印这个帮助。

选择执行

尽管Libdoc只有使用Python在上面的简介中,它的工作原理 也与Jython和IronPython。 当记录Java库,Jython 实际需要。

在简介Libdoc执行作为一个模块安装 ( python - m robot.libdoc )。 除此之外,它还可以运行 一个脚本:

python path/robot/libdoc.py [options] arguments

执行一个脚本可以是有用的,如果你所做的 手动安装 或者只有 机器人 与源代码目录 在您的系统。

指定库或资源文件

Python库和动态库名称或路径

当记录库使用Python实现或使用 动态库的API ,可以通过指定图书馆 仅使用库名称或路径库源代码。 在前者情况下,图书馆是搜索使用 模块搜索路径 和它的名字必须在相同的格式机器人框架测试数据。

如果这些库需要在导入参数时,参数 必须加库名称或路径使用两个冒号呢 MyLibrary:__arg1::最长 。 如果参数改变关键词库 提供了或者改变它的文档,它可能是一个好主意 ——名字 选项也相应改变库名称。

Java库的路径

一个Java测试库使用的实现 静态库API 可以 给指定的路径包含源代码文件 库的实现。 此外, tools.jar ,这是 Java JDK的分布,必须找到 类路径 当 Libdoc执行。 注意,Java生成文档 图书馆只有Jython工作。

资源文件的路径

资源文件必须使用指定的路径。 如果路径是 不存在,资源文件中所有目录搜索 的 模块搜索路径 同样当执行测试用例。

生成文档

在HTML或XML格式生成文档时,输出文件必须 被指定为第二个参数后,图书馆/资源名称或路径。 输出格式是自动从扩展但也可以设置 使用 - - -格式 选择。

例子:

python -m robot.libdoc OperatingSystem OperatingSystem.html
python -m robot.libdoc --name MyLibrary Remote::http://10.0.0.42:8270 MyLibrary.xml
python -m robot.libdoc test/resource.html doc/resource_doc.html
jython -m robot.libdoc --version 1.0 MyJavaLibrary.java MyJavaLibrary.html
jython -m robot.libdoc my.organization.DynamicJavaLibrary my.organization.DynamicJavaLibrary.xml

查看控制台信息

Libdoc有三个特殊的命令在控制台上显示信息。 使用这些命令输出文件的名称,而是和他们可以 也附加参数。

列表

列表的名称关键词库/资源包含。 可以 限于只显示某些关键词通过可选模式 作为参数。 关键词列出其名称是否包含给定的模式。

显示

显示库/资源文档。 只能是有限的显示吗 某些关键词通过名称作为参数。 如果显示关键字 它的名字匹配任何名字。 特别的观点 介绍 将显示 只有图书馆引进和导入部分。

版本

显示库版本

可选模式给 列表 和 显示 情况和空间 不敏感。 同时也接受 * 和 吗? 作为通配符。

例子:

python -m robot.libdoc Dialogs list
python -m robot.libdoc Selenium2Library list browser
python -m robot.libdoc Remote::10.0.0.42:8270 show
python -m robot.libdoc Dialogs show PauseExecution execute*
python -m robot.libdoc Selenium2Library show intro
python -m robot.libdoc Selenium2Library version

编写文档

本节讨论编写文档 Python 和 Java 基础测试 库以及使用静态库的API 动态库 和 资源文件 。 创建测试库 和 资源文件 是 描述的更详细的信息在用户指南。

Python库

文档使用的Python库 静态库API 写简单的文档字符串库类或模块和 方法实现的关键字。 文档的第一行方法 视为一个简短的文档关键字(例如,使用 工具提示在生成的HTML文档的链接),它应该 因此尽可能地描述,但时间不会太长。

下面这个简单的例子说明了如何编写的文档 一般,有一个 稍长点的例子 最后这一点 章还包含生成的文档的一个例子。

class ExampleLib:
    """Library for demo purposes.

    This library is only used in an example and it doesn't do anything useful.
    """

    def my_keyword(self):
        """Does nothing."""
        pass

    def your_keyword(self, arg):
        """Takes one argument and *does nothing* with it.

        Examples:
        | Your Keyword | xxx |
        | Your Keyword | yyy |
        """
        pass

提示

如果你想使用非ascii文件的生产 Python库,您必须使用utf - 8作为你的 源代码 编码 或创建文档字符串是Unicode。

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

Java库

文档使用的Java库 静态库API 写 正常 Javadoc注释 库类和方法。 在这种情况下 Libdoc实际使用Javadoc工具内部,因此 tools.jar 包含必须的 类路径 。 这个jar文件的一部分 正常的Java SDK分布和应该发现 本 Java SDK安装目录之下。

以下简单的例子有完全相同的文档(功能) 比之前的Python示例。

/**
 * Library for demo purposes.
 *
 * This library is only used in an example and it doesn't do anything useful.
 */
public class ExampleLib {

    /**
     * Does nothing.
     */
    public void myKeyword() {
    }

    /**
     * Takes one argument and *does nothing* with it.
     *
     * Examples:
     * | Your Keyword | xxx |
     * | Your Keyword | yyy |
     */
    public void yourKeyword(String arg) {
    }
}

动态库

能够产生有意义的动态库的文档, 图书馆必须返回关键字参数名称和文档使用 get_keyword_arguments 和 get_keyword_documentation 方法(或使用他们camelCase变体 getKeywordArguments和 getKeywordDocumentation )。 图书馆还可以支持 一般图书馆通过特殊文档 __intro__ 和 __init__ 值 get_keyword_documentation 方法。

看到 动态库的API 部分关于如何的更多信息 创建这些方法。

导入部分

一个单独的部分图书馆如何创建基于其进口 初始化方法。 Python库,如果它有一个 __init__ 方法的参数除了 自我 ,它的文档和 参数显示。 Java库,如果它有一个公共构造函数 接受参数,其所有公共构造函数所示。

class TestLibrary:

    def __init__(self, mode='default')
        """Creates new TestLibrary. `mode` argument is used to determine mode."""
        self.mode = mode

    def some_keyword(self, arg):
        """Does something based on given `arg`.

        What is done depends on the `mode` specified when `importing` the library.
        """
        if self.mode == 'secret':
             # ...

资源文件的文档

资源文件中的关键字可以有文档使用 (文档) 设置,这个文档也使用 Libdoc。 第一行的文档(直到第一 隐式的换行符 或显式 \ n )被认为是短的 文档同样与测试库。

资源文件本身也可以 文档 在 设置表记录整个资源文件。

可能的资源文件中的变量不能被记录下来。

*** Settings ***
Documentation    Resource file for demo purposes.
...              This resource is only used in an example and it doesn't do anything useful.

*** Keywords ***
My Keyword
    [Documentation]   Does nothing
    No Operation

Your Keyword
    [Arguments]  ${arg}
    [Documentation]   Takes one argument and *does nothing* with it.
    ...
    ...    Examples:
    ...    | Your Keyword | xxx |
    ...    | Your Keyword | yyy |
    No Operation

5.1.3文档语法

Libdoc机器人框架的支持文档 文档 语法 、HTML、文本和 reStructuredText 。 可以使用的格式 中指定的 测试库的源代码 使用 ROBOT_LIBRARY_DOC_FORMAT 属性或从命令行得到使用——docformat(f) 选择。 在这两种情况下可能的不区分大小写的值 机器人 (默认), HTML , 文本 和 休息 。

机器人框架的文档格式是默认和一般 推荐格式。 使用现有的其他格式时尤其有用 在测试代码与现有文档库。 支持其他格式 2.7.5添加机器人框架。

机器人框架文档的语法

在机器人框架的最重要的特性 文档的语法 是 格式使用 *大胆的* 和 _italic_ 、自定义链接和 自动转换的url链接,创建表和可能性 预格式化的文本块(有用的例子)仅仅与管的性格。 如果文档长,支持章节标题(新机器人 框架2.7.5)也可以方便。

一些最重要的格式化特性的示例 在下面。 请注意,因为这是默认格式,不需要使用 ROBOT_LIBRARY_DOC_FORMAT 属性也不给这个命令的格式 线。

"""Example library in Robot Framework format.

- Formatting with *bold* and _italic_.
- URLs like http://example.com are turned to links.
- Custom links like [http://robotframework.org|Robot Framework] are supported.
- Linking to `My Keyword` works.
"""

def my_keyword():
    """Nothing more to see here."""

HTML文档的语法

当使用HTML格式,您可以创建文档几乎免费使用 任何语法。 主要缺点是HTML标记不是人类友好, 在源代码中,可以使文档很难维护和阅读。 使用HTML格式的文档Libdoc直接没有任何 转换或逃跑。 的特殊语法 链接的关键字 使用 语法就像 “我的关键词” 然而,支持。

在下面的例子包含格式范例与前面的示例相同。 现在 ROBOT_LIBRARY_DOC_FORMAT 属性必须使用或格式 在命令行上 ——docformat HTML 。

"""Example library in HTML format.

<ul>
  <li>Formatting with <b>bold</b> and <i>italic</i>.
  <li>URLs are not turned to links automatically.
  <li>Custom links like <a href="http://www.w3.org/html">HTML</a> are supported.
  <li>Linking to `My Keyword` works.
</ul>
"""
ROBOT_LIBRARY_DOC_FORMAT = 'HTML'

def my_keyword():
    """Nothing more to see here."""

纯文本文档的语法

当使用纯文本格式时,原有Libdoc使用文档。 换行和其他保留空格缩进,除外 HTML特殊字符( < > & )逃脱了。 唯一的格式做的是 将url转化为可点击的链接和支持 内部链接 就像“我的关键词” 。

"""Example library in plain text format.

- Formatting is not supported.
- URLs like http://example.com are turned to links.
- Custom links are not supported.
- Linking to `My Keyword` works.
"""
ROBOT_LIBRARY_DOC_FORMAT = 'text'

def my_keyword():
    """Nothing more to see here"""

reStructuredText文档语法

reStructuredText 是简单而强大的标记语法广泛应用在Python中 项目(包括本用户指南)和其他地方。 主要的限制 是你需要的吗 docutils 模块安装能够生成 文档中使用它。 因为撇号人物具有特殊的意义 恰好, 链接的关键字 需要他们逃脱了 \ ' \ '我的关键字 。

"""Example library in reStructuredText format.

- Formatting with **bold** and *italic*.
- URLs like http://example.com are turned to links.
- Custom links like reStructuredText__ are supported.
- Linking to \`My Keyword\` works but requires backtics to be escaped.

__ http://docutils.sourceforge.net
"""
ROBOT_LIBRARY_DOC_FORMAT = 'reST'

def my_keyword():
    """Nothing more to see here"""

5.1.4内部链接

Libdoc支持内部链接关键字和不同 部分在文档中。 连接是通过周围 用撇号字符目标名称 “目标” 。 目标 名称不区分大小写和可能的目标是在解释道 随后的章节。

没有任何错误或警告如果没有找到链接目标,而是Libdoc 刚刚在斜体格式文本。 早些时候这个格式是推荐的 是用来指关键字参数,但这是有问题的,因为 可能不小心创建内部链接。 现在建议 使用 内联代码风格 双引号的像 “论证” 代替。 旧的格式单引号 甚至可能被移除在未来支持链接时给了一个错误 没有找到目标。

除了以下部分中的示例,内部链接 和参数的显示格式 更长时间的例子 在 这一章的结束。

链接的关键字

所有的关键词库自动创建链接的目标,他们可以 有关使用语法 “关键字名称” 。 这是说明 下面的例子在关键字都有对方的链接。

def keyword(log_level="INFO"):
    """Does something and logs the output using the given level.

    Valid values for log level` are "INFO" (default) "DEBUG" and "TRACE".

    See also `Another Keyword`.
    """
    # ...

def another_keyword(argument, log_level="INFO"):
    """Does something with the given argument else and logs the output.

    See `Keyword` for information about valid log levels.
    """
    # ...

请注意

当使用 reStructuredText文档语法 ,引号必须 逃过像 \ '关键字名称\ ' 。

链接到自动部分

Libdoc总是包含生成的文档部分 图书馆整体介绍,快捷键字, 实际的关键词。 如果一个库本身需要参数,也有 单独的 导入部分 。

所有这些部分作为目标,可以联系,和可能的 在下表中列出目标名称。 使用这些目标是 下一节的例子所示。

自动部分链接的目标

部分	目标
介绍	“介绍” 和 “图书馆介绍”
进口	“导入” 和 “库导入”
快捷键	“快捷键” 2.7.5机器人框架。(新)
关键字	“关键词” 2.7.5机器人框架。(新)

链接自定义部分

从2.7.5版开始,机器人框架的 文档的语法 支持自定义 章节标题 ,使用的标题 库或资源文件介绍自动创建链接 目标。 下面的例子说明了连接和自动 自定义的部分:

"""Library for Libdoc demonstration purposes.

This library does not do anything useful.

= My section  =

We do have a custom section in the documentation, though.
"""

def keyword():
    """Does nothing.

    See `introduction` for more information and `My section` to test how
    linking to custom sections works.
    """
    pass

请注意

链接只能在使用自定义部分 机器人框架 文档的语法 。

请注意

机器人框架2.8之前,只有第一层部分 标题可链接。

所以自动Libdoc处理关键字”参数 参数指定方法在图书馆或用户关键词 资源文件在一个单独的列中列出。 用户关键字参数 没有显示 $ { } 或 @ { } 使论点看起来 相同关键字源自哪里。

无论关键词是如何实现,Libdoc显示参数 同样当创建Python中的关键词。 这个格式是解释 更彻底地在下表中。

如何Libdoc代表参数

参数	现在代表	例子
没有参数	空的列。
一个或多个 论点	字符串列表包含 参数名称。	one_argument a1,a2,a3
默认值 为参数	默认值分离 从名字 = 。	arg =默认值 a、b = 1,c = 2
变量的数量 的参数 (可变参数)	最后(或第二 kwargs)参数 * 它的名字。	*可变参数 a、b = 42岁*休息
免费的关键字 参数(kwargs)	最后一个参数 * * 它的名字。	* * kwargs a、b = 42 * * kws * * kwargs *可变参数

指在关键字参数文档,建议 使用 内联代码风格 就像 “论证” 。

Libdoc例子

下面的例子说明了如何使用最重要的 文档格式 的可能性, 内部链接 ,所以 上。 点击这里 如何生成的文档的样子。

class LoggingLibrary:
    """Library for logging messages.

    = Table of contents =

    - `Usage`
    - `Valid log levels`
    - `Examples`
    - `Importing`
    - `Shortcuts`
    - `Keywords`

    = Usage =

    This library has several keyword, for example `Log Message`, for logging
    messages. In reality the library is used only for _Libdoc_ demonstration
    purposes.

    = Valid log levels =

    Valid log levels are ``INFO``, ``DEBUG``, and ``TRACE``. The default log
    level can be set during `importing`.

    = Examples =

    Notice how keywords are linked from examples.

    | `Log Message`      | My message    |                |               |
    | `Log Two Messages` | My message    | Second message | level=DEBUG   |
    | `Log Messages`     | First message | Second message | Third message |
    """
    ROBOT_LIBRARY_VERSION = '0.1'

    def __init__(self, default_level='INFO'):
        """The default log level can be given at library import time.

        See `Valid log levels` section for information about available log
        levels.

        Examples:

        | =Setting= |     =Value=    | =Value= |          =Comment=         |
        | Library   | LoggingLibrary |         | # Use default level (INFO) |
        | Library   | LoggingLibrary | DEBUG   | # Use the given level      |
        """
        self.default_level = self._verify_level(default_level)

    def _verify_level(self, level):
        level = level.upper()
        if level not in ['INFO', 'DEBUG', 'TRACE']:
            raise RuntimeError("Invalid log level'%s'. Valid levels are "
                               "'INFO', 'DEBUG', and 'TRACE'")
        return level

    def log_message(self, message, level=None):
        """Writes given message to the log file using the specified log level.

        The message to log and the log level to use are defined using
        ``message`` and ``level`` arguments, respectively.

        If no log level is given, the default level given during `library
        importing` is used.
        """
        level = self._verify_level(level) if level else self.default_level
        print "*%s* %s" % (level, message)

    def log_two_messages(self, message1, message2, level=None):
        """Writes given messages to the log file using the specified log level.

        See `Log Message` keyword for more information.
        """
        self.log_message(message1, level)
        self.log_message(message2, level)

    def log_messages(self, *messages):
        """Logs given messages using the log level set during `importing`.

        See also `Log Message` and `Log Two Messages`.
        """
        for msg in messages:
            self.log_message(msg)

所有 标准库 已生成的文档 Libdoc及其文档(和源代码)作为更多 现实的例子。