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.
- Formatting with bold and italic.
- URLs are not turned to links automatically.
- Custom links like HTML are supported.
- Linking to `My Keyword` works.
""" 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中的关键词。 这个格式是解释 更彻底地在下表中。
| 参数 | 现在代表 | 例子 |
|---|---|---|
| 没有参数 | 空的列。 | |
| 一个或多个 论点 | 字符串列表包含 参数名称。 |
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及其文档(和源代码)作为更多 现实的例子。