robotframework笔记25

library文档工具(Libdoc)

和其他 工具。 Libdoc显示库或也有几个特殊的命令 在控制台上资源信息。

可以创建文档:

• 使用正常 静态库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]

选项

< html | xml >
	指定是否要生成HTML或XML输出。 如果不使用此选项,格式 扩展的输出文件。
<机器人其他html文本| | | >
	。 2.7.5新机器人框架。
<新名称>
	集的名字记录库或资源。
<新版本>
	。
<路径>
	。
<什么:>
	输出。
——帮助	打印这个帮助。

选择执行

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

)。 除此之外,它还可以运行 一个脚本:

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

与源代码目录 在您的系统。

指定库或资源文件

Python库和动态库名称或路径

和它的名字必须在相同的格式机器人框架测试数据。

选项也相应改变库名称。

Java库的路径

当 Libdoc执行。 注意,Java生成文档 图书馆只有Jython工作。

资源文件的路径

同样当执行测试用例。

生成文档

选择。

例子:

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库

写简单的文档字符串库类或模块和 方法实现的关键字。 文档的第一行方法 视为一个简短的文档关键字(例如,使用 工具提示在生成的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

提示

或创建文档字符串是Unicode。

。

Java库

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) {
    }
}

动态库

方法。

部分关于如何的更多信息 创建这些方法。

导入部分

,它的文档和 参数显示。 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':
             # ...

资源文件的文档

)被认为是短的 文档同样与测试库。

在 设置表记录整个资源文件。

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

*** 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文档语法

。

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

机器人框架文档的语法

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

属性也不给这个命令的格式 线。

"""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文档的语法

然而,支持。

。

"""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."""

纯文本文档的语法

。

"""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文档语法

。

"""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内部链接

。 目标 名称不区分大小写和可能的目标是在解释道 随后的章节。

代替。 旧的格式单引号 甚至可能被移除在未来支持链接时给了一个错误 没有找到目标。

在 这一章的结束。

链接的关键字

。 这是说明 下面的例子在关键字都有对方的链接。

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.
    """
    # ...

请注意

。

链接到自动部分

。

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

自动部分链接的目标

部分	目标
介绍	“图书馆介绍”
进口	“库导入”
快捷键	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显示参数 同样当创建Python中的关键词。 这个格式是解释 更彻底地在下表中。

如何Libdoc代表参数

参数	现在代表	例子
没有参数	空的列。
一个或多个 论点	字符串列表包含 参数名称。	one_argument a1,a2,a3
默认值 为参数	。	arg =默认值 a、b = 1,c = 2
变量的数量 的参数 (可变参数)	它的名字。	*可变参数 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及其文档(和源代码)作为更多 现实的例子。