libdoc.py

libdoc.py is a tool for generating keyword documentation for test libraries and resource files in HTML and XML formats. Documentation can be created for both test libraries and resource files. Starting from Robot Framework 2.1.2 it is also possible to upload documentation to RFDoc service.

libdoc.py is included in source distributions and can also be downloaded from http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool.

Table of contents

Synopsis

libdoc.py [options] library_or_resource_file

Options

-a, --argument <value>
 Possible arguments that a library needs.
-f, --format <html|xml>
 Specifies whether to generate HTML or XML output. Since 2.1.2 version the default value is got from the output file extension. With earlier versions, or if the output is not specified, the default is HTML.
-o, --output <path>
 Either a directory or a file where to write the generated documentation or a URL where to upload it. If a path pointing to a directory is used, the documentation is written there using a name like <name>.<format>. If a file with that name already exists, an index is added after the <name> part. If the path starts with http://, it is assumed to be a URL to RFDoc's upload page and the documentation is uploaded there. Otherwise the path is used directly as a file name and possible existing files are overwritten. The default value for the path is the directory where the script is executed from.
-N, --name <newname>
 Sets the name of the documented library or resource.
-T, --title <title>
 Sets the title of the generated HTML documentation. Underscores in the given title are automatically converted to spaces.
-S, --styles <styles>
 Overrides the default styles. If the given styles is a path to an existing files, styles will be read from it. If it is a string NONE, no styles will be used. Otherwise the given text is used as-is.
-P, --pythonpath <path>
 Additional path(s) to insert into PYTHONPATH.
-E, --escape <what:with>
 Escapes characters which are problematic in console. what is the name of the character to escape and with is the string to escape it with. Available escapes are listed in the --help output.
-h, --help Prints this help.

Description

libdoc.py is a tool for generating keyword documentation for test libraries and resource files in HTML and XML formats. The former format is suitable for humans and the latter for RIDE, RFDoc and other tools. It is even possible to upload the XML documentation to RFDoc systems.

Documentation can be created for:

Additionally it is possible to use XML documentation created earlier by libdoc.py or other tools as input. This allows uploading these XML documents to RFDoc and generating stand-alone HTML documentation from them.

Specifying the library or resource file

It is possible to specify a Python test library by giving either the path to the source or only the library name. If the library name is used, it must be in the same format as in the Robot Framework test data when importing libraries. In this case, the library is searched from PYTHONPATH (and from CLASSPATH, if on Jython).

A Java test library implemented with a normal library API can be specified by giving the path to the source code file containing the library implementation. Additionally, tools.jar, which is part of the Sun JDK distribution, must be found from CLASSPATH when libdoc.py is executed. When generating documentation for Java libraries, libdoc.py must be executed using Jython.

Libraries using the dynamic library API are handled in the same way as Python libraries.

Some libraries require arguments when they are imported and they can be given using --argument option. It can be used multiple times to specify multiple arguments. Libraries always get these arguments as strings. If arguments change what keywords the library provides or otherwise change its behavior, it might be a good idea to use --name option to also change the library name accordingly.

Resource files must always be specified using a path. If the path does not exist, resource files are also searched from all directories in PYTHONPATH.

Uploading documentation

Uploading the generated documentation to RFDoc is as easy as specifying the URL to the RFDoc upload page using --output option. This URL must always start with http://. It is possible to upload all documentations to RFDoc and input can also be an earlier created XML documentation.

Examples

python libdoc.py OperatingSystem
python libdoc.py --output doc/MyLib.html src/MyLib.py
python libdoc.py --argument arg1 --argument arg2 LibraryWithArgs.py
python libdoc.py --name MyLibrary --argument 10.0.0.42:8270 Remote.py
python libdoc.py test/resource.html
python libdoc.py --format xml OperatingSystem
python libdoc.py --format xml --output doc test/resource.html
jython libdoc.py --output MyJavaLibrary.xml MyJavaLibrary.java
python libdoc.py --output http://rfdoc.mydomain/upload MyLibrary
python libdoc.py --output http://rfdoc.mydomain/upload specs/Lib.xml

Writing documentation

For more information about how to actually create test libraries and resource files see Robot Framework User Guide.

Python libraries

The documentation for Python libraries is written simply as doc strings for the library class and for methods implementing keywords. The first line of the method documentation is considered as a short documentation for the keywords (used for example as a tool tip in links in the generated HTML documentation), and it should thus be as describing as possible, but not too long.

The simple example below illustrates how to write the documentation, and for example standard libraries give more realistic examples. For more information on Python documentation strings, see PEP-257.

class ExampleLib:
    """Library for demo purposes.

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

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

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

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

Java libraries

When writing documentation for a normal Java library, conventions for writing Javadoc should be used. The documentation is generated based on the Javadocs in the source files. For example following simple example has exactly same documentation (and functionality) than the earlier Python example.

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

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

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

Dynamic libraries

To be able to generate meaningful documentation for dynamic libraries, they must return keyword argument names and documentation using get_keyword_arguments and get_keyword_documentation methods (or using their camelCase variants getKeywordArguments and getKeywordDocumentation). See the User Guide for more information about how to create these methods and the dynamic library API in general.

Importing section

A separate section about how the library is imported is created based on its initialization methods. For a Python library, if it has an __init__ method that takes arguments in addition to self, the documentation of that method is shown. For a Java library, if it has a constructor that accepts arguments, all its constructors and their javadocs are shown.

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):
        if self.mode == 'secret':
             # ...

Resource files

Keywords in resource files can have documentation using [Documentation] setting, and this documentation is also used by libdoc.py. First line of the documentation (until the first \n) is considered to be the short documentation similarly as with test libraries.

Starting from Robot Framework 2.1 also the resource file itself can have Documentation in the Setting table for documenting the whole resource file.

Possible variables in resource files are not documented.

An example resource file
Setting Value Value
Documentation Resource file for demo purposes.\n  
... This resource is only used in an example and it does't do anything useful.
Keyword Action Argument Argument
My Keyword [Documentation] Does nothing  
  No Operation    
       
Your Keyword [Arguments] ${arg}  
  [Documentation] Takes one argument and *does nothing* with it.\n
Example:\n
| Your Keyword | xxx |\n
| Your Keyword | yyy |\n
  No Operation    

Documentation syntax

Generic formatting rules

The User Guide has an appendix explaining different documentation formatting possibilities supported by Robot Framework. Most important features are formatting using *bold* and _italic_, automatic conversion of URLs to clickable links, and the possibility to create tables (useful for examples) simply with pipe character:

| Some Keyword    | arg |
| Another Keyword |     |

Special formatting and internal linking

In addition to the formatting explained in the User Guide, libdoc.py supports also special formatting of keyword names and arguments with backtick character `. Even more importantly, this syntax also automatically creates internal links to other keywords in the library. For example documentation of the following simple Python library would have link from Log Messages to Log Message, and `message` and `level` would be formatted specially.

def log_message(message, level="INFO"):
    """Writes given message to log using specified log level.

    `message` can be any object. Valid values for `level` are "INFO" (default),
    "DEBUG" and "TRACE".
    """
    print "*%s* %s" % (level, message)

def log_messages(message1, message2, level="INFO"):
    """Writes given messages to log using specified log level.

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

Additionally, using `introduction` or `library introduction` (case insensitive) generates a link to the library introduction in the beginning of the generated documentation. Similarly `importing` or `library importing` generates a link to the importing section.

Internal linking between keywords is used by all standard libraries, so their documentation (and source) acts as a more realistic example.

Keywords' arguments

libdoc.py handles keywords' arguments automatically so that arguments specified for methods in libraries or user keywords in resource files are listed in a separate column. Possible trailing underscores in argument names are stripped to make it possible to use arguments like list_ in the code and still have list in documentation. Additionally, user keyword arguments are shown without ${} or @{} to make arguments look the same regardless where keywords originated from.