Libdoc是机器人框架内置的工具生成的关键字的文档测试库和资源文件的HTML和XML格式。前格式适用于人类,后者骑和其他工具。Libdoc显示库或也有几个特殊的命令在控制台上资源信息。
可以创建文档:
另外可以使用Libdoc创建的XML规范作为输入。
python-mrobot.libdoc[options]library_or_resourceoutput_filepython-mrobot.libdoc[options]library_or_resourcelist|show|version[names]选项-f,---格式
在简介Libdoc执行作为一个模块安装(python-mrobot.libdoc)。除此之外,它还可以运行一个脚本:
pythonpath/robot/libdoc.py[options]arguments执行一个脚本可以是有用的,如果你所做的手动安装或者只有机器人与源代码目录在您的系统。
当记录库使用Python实现或使用动态库的API,可以通过指定图书馆仅使用库名称或路径库源代码。在前者情况下,图书馆是搜索使用模块搜索路径和它的名字必须在相同的格式机器人框架测试数据。
如果这些库需要在导入参数时,参数必须加库名称或路径使用两个冒号呢MyLibrary:__arg1::最长。如果参数改变关键词库提供了或者改变它的文档,它可能是一个好主意——名字选项也相应改变库名称。
一个Java测试库使用的实现静态库API可以给指定的路径包含源代码文件库的实现。此外,tools.jar,这是JavaJDK的分布,必须找到类路径当Libdoc执行。注意,Java生成文档图书馆只有Jython工作。
资源文件必须使用指定的路径。如果路径是不存在,资源文件中所有目录搜索的模块搜索路径同样当执行测试用例。
在HTML或XML格式生成文档时,输出文件必须被指定为第二个参数后,图书馆/资源名称或路径。输出格式是自动从扩展但也可以设置使用---格式选择。
例子:
可选模式给列表和显示情况和空间不敏感。同时也接受*和吗作为通配符。
python-mrobot.libdocDialogslistpython-mrobot.libdocSelenium2Librarylistbrowserpython-mrobot.libdocRemote::10.0.0.42:8270showpython-mrobot.libdocDialogsshowPauseExecutionexecute*python-mrobot.libdocSelenium2Libraryshowintropython-mrobot.libdocSelenium2Libraryversion编写文档本节讨论编写文档Python和Java基础测试库以及使用静态库的API动态库和资源文件。创建测试库和资源文件是描述的更详细的信息在用户指南。
下面这个简单的例子说明了如何编写的文档一般,有一个稍长点的例子最后这一点章还包含生成的文档的一个例子。
classExampleLib:"""Libraryfordemopurposes.Thislibraryisonlyusedinanexampleanditdoesn'tdoanythinguseful."""defmy_keyword(self):"""Doesnothing."""passdefyour_keyword(self,arg):"""Takesoneargumentand*doesnothing*withit.Examples:|YourKeyword|xxx||YourKeyword|yyy|"""pass提示
如果你想使用非ascii文件的生产Python库,您必须使用utf-8作为你的源代码编码或创建文档字符串是Unicode。
有关Python文档字符串的更多信息,请参阅pep-257。
文档使用的Java库静态库API写正常Javadoc注释库类和方法。在这种情况下Libdoc实际使用Javadoc工具内部,因此tools.jar包含必须的类路径。这个jar文件的一部分正常的JavaSDK分布和应该发现本JavaSDK安装目录之下。
以下简单的例子有完全相同的文档(功能)比之前的Python示例。
/***Libraryfordemopurposes.**Thislibraryisonlyusedinanexampleanditdoesn'tdoanythinguseful.*/publicclassExampleLib{/***Doesnothing.*/publicvoidmyKeyword(){}/***Takesoneargumentand*doesnothing*withit.**Examples:*|YourKeyword|xxx|*|YourKeyword|yyy|*/publicvoidyourKeyword(Stringarg){}}动态库能够产生有意义的动态库的文档,图书馆必须返回关键字参数名称和文档使用get_keyword_arguments和get_keyword_documentation方法(或使用他们camelCase变体getKeywordArguments和getKeywordDocumentation)。图书馆还可以支持一般图书馆通过特殊文档__intro__和__init__值get_keyword_documentation方法。
看到动态库的API部分关于如何的更多信息创建这些方法。
一个单独的部分图书馆如何创建基于其进口初始化方法。Python库,如果它有一个__init__方法的参数除了自我,它的文档和参数显示。Java库,如果它有一个公共构造函数接受参数,其所有公共构造函数所示。
classTestLibrary:def__init__(self,mode='default')"""CreatesnewTestLibrary.`mode`argumentisusedtodeterminemode."""self.mode=modedefsome_keyword(self,arg):"""Doessomethingbasedongiven`arg`.Whatisdonedependsonthe`mode`specifiedwhen`importing`thelibrary."""ifself.mode=='secret':#...资源文件的文档资源文件中的关键字可以有文档使用(文档)设置,这个文档也使用Libdoc。第一行的文档(直到第一隐式的换行符或显式\n)被认为是短的文档同样与测试库。
资源文件本身也可以文档在设置表记录整个资源文件。
可能的资源文件中的变量不能被记录下来。
***Settings***DocumentationResourcefilefordemopurposes....Thisresourceisonlyusedinanexampleanditdoesn'tdoanythinguseful.***Keywords***MyKeyword[Documentation]DoesnothingNoOperationYourKeyword[Arguments]${arg}[Documentation]Takesoneargumentand*doesnothing*withit.......Examples:...|YourKeyword|xxx|...|YourKeyword|yyy|NoOperation5.1.3文档语法Libdoc机器人框架的支持文档文档语法、HTML、文本和reStructuredText。可以使用的格式中指定的测试库的源代码使用ROBOT_LIBRARY_DOC_FORMAT属性或从命令行得到使用——docformat(f)选择。在这两种情况下可能的不区分大小写的值机器人(默认),HTML,文本和休息。
机器人框架的文档格式是默认和一般推荐格式。使用现有的其他格式时尤其有用在测试代码与现有文档库。支持其他格式2.7.5添加机器人框架。
在机器人框架的最重要的特性文档的语法是格式使用*大胆的*和_italic_、自定义链接和自动转换的url链接,创建表和可能性预格式化的文本块(有用的例子)仅仅与管的性格。如果文档长,支持章节标题(新机器人框架2.7.5)也可以方便。
一些最重要的格式化特性的示例在下面。请注意,因为这是默认格式,不需要使用ROBOT_LIBRARY_DOC_FORMAT属性也不给这个命令的格式线。
在下面的例子包含格式范例与前面的示例相同。现在ROBOT_LIBRARY_DOC_FORMAT属性必须使用或格式在命令行上——docformatHTML。
没有任何错误或警告如果没有找到链接目标,而是Libdoc刚刚在斜体格式文本。早些时候这个格式是推荐的是用来指关键字参数,但这是有问题的,因为可能不小心创建内部链接。现在建议使用内联代码风格双引号的像“论证”代替。旧的格式单引号甚至可能被移除在未来支持链接时给了一个错误没有找到目标。
所有的关键词库自动创建链接的目标,他们可以有关使用语法“关键字名称”。这是说明下面的例子在关键字都有对方的链接。
defkeyword(log_level="INFO"):"""Doessomethingandlogstheoutputusingthegivenlevel.Validvaluesforloglevel`are"INFO"(default)"DEBUG"and"TRACE".Seealso`AnotherKeyword`."""#...defanother_keyword(argument,log_level="INFO"):"""Doessomethingwiththegivenargumentelseandlogstheoutput.See`Keyword`forinformationaboutvalidloglevels."""#...请注意
当使用reStructuredText文档语法,引号必须逃过像\'关键字名称\'。
Libdoc总是包含生成的文档部分图书馆整体介绍,快捷键字,实际的关键词。如果一个库本身需要参数,也有单独的导入部分。
所有这些部分作为目标,可以联系,和可能的在下表中列出目标名称。使用这些目标是下一节的例子所示。
从2.7.5版开始,机器人框架的文档的语法支持自定义章节标题,使用的标题库或资源文件介绍自动创建链接目标。下面的例子说明了连接和自动自定义的部分:
"""LibraryforLibdocdemonstrationpurposes.Thislibrarydoesnotdoanythinguseful.=Mysection=Wedohaveacustomsectioninthedocumentation,though."""defkeyword():"""Doesnothing.See`introduction`formoreinformationand`Mysection`totesthowlinkingtocustomsectionsworks."""pass请注意
链接只能在使用自定义部分机器人框架文档的语法。
请注意
机器人框架2.8之前,只有第一层部分标题可链接。
所以自动Libdoc处理关键字”参数参数指定方法在图书馆或用户关键词资源文件在一个单独的列中列出。用户关键字参数没有显示${}或@{}使论点看起来相同关键字源自哪里。
无论关键词是如何实现,Libdoc显示参数同样当创建Python中的关键词。这个格式是解释更彻底地在下表中。
指在关键字参数文档,建议使用内联代码风格就像“论证”。
下面的例子说明了如何使用最重要的文档格式的可能性,内部链接,所以上。点击这里如何生成的文档的样子。