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及其文檔(和源代碼)作為更多 現實的例子。