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

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.

Documentation formatting

The user guide has an appendix explaining different documentation formatting possibilities. 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 |     |

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.

Keyword arguments

libdoc.py handles keyword arguments automatically so that arguments specified for methods in libraries or user keywords in resource files are listed in a separate column. Possible trailing spaces 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.