/usr/bin/libdoc

Libdoc -- Robot Framework library documentation generator

Version:  7.4.2 (Python 3.10.22 on linux)

Usage:  libdoc [options] library_or_resource output_file
   or:  libdoc [options] library_or_resource list|show|version [names]

Libdoc can generate documentation for Robot Framework libraries and resource
files. It can generate HTML documentation for humans as well as machine
readable spec files in XML and JSON formats. Libdoc also has few special
commands to show library or resource information on the console.

Libdoc supports all library and resource types and also earlier generated XML
and JSON specs can be used as input. If a library needs arguments, they must be
given as part of the library name and separated by two colons, for example,
like `LibraryName::arg1::arg2`.

The easiest way to run Libdoc is using the `libdoc` command created as part of
the normal installation. Alternatively it is possible to execute the
`robot.libdoc` module directly like `python -m robot.libdoc`, where `python`
can be replaced with any supported Python interpreter. Yet another alternative
is running the module as a script like `python path/to/robot/libdoc.py`.

Options
=======

 -f --format HTML|XML|JSON|LIBSPEC
                          Specifies whether to generate an HTML output for
                          humans or a machine readable spec file in XML or JSON
                          format. The LIBSPEC format means XML spec with
                          documentations converted to HTML. The default format
                          is got from the output file extension.
 -s --specdocformat RAW|HTML
                          Specifies the documentation format used with XML and
                          JSON spec files. RAW means preserving the original
                          documentation format and HTML means converting
                          documentation to HTML. The default is RAW with XML
                          spec files and HTML with JSON specs and when using
                          the special LIBSPEC format.
 -F --docformat ROBOT|HTML|TEXT|REST
                          Specifies the source documentation format. Possible
                          values are Robot Framework's documentation format,
                          HTML, plain text, and reStructuredText. The default
                          value can be specified in library source code and
                          the initial default value is ROBOT.
    --theme DARK|LIGHT|NONE
                          Use dark or light HTML theme. If this option is not
                          used, or the value is NONE, the theme is selected
                          based on the browser color scheme. New in RF 6.0.
    --language lang       Set the default language used in HTML outputs.
                          `lang` must be one of the built-in language codes:
                          - EN
                          - FI
                          - FR
                          - IT
                          - NL
                          - PT-BR
                          - PT-PT
                          New in RF 7.2.
 -n --name name           Sets the name of the documented library or resource.
 -v --version version     Sets the version of the documented library or
                          resource.
    --quiet               Do not print the path of the generated output file
                          to the console.
 -P --pythonpath path *   Additional locations where to search for libraries
                          and resources.
 -h -? --help             Print this help.

Creating documentation
======================

When creating documentation in HTML, XML or JSON format, the output file must
be specified as the second argument after the library or resource name or path.

Output format is got automatically from the output file extension. In addition
to `*.html`, `*.xml` and `*.json` extensions, it is possible to use the special
`*.libspec` extensions which means XML spec with actual library and keyword
documentation converted to HTML. The format can also be set explicitly using
the `--format` option.

Examples:

  libdoc src/MyLibrary.py doc/MyLibrary.html
  libdoc doc/MyLibrary.json doc/MyLibrary.html
  libdoc --name MyLibrary Remote::10.0.0.42:8270 MyLibrary.xml
  libdoc MyLibrary MyLibrary.libspec

Viewing information on console
==============================

Libdoc has three special commands to show information on the console. These
commands are used instead of the name of the output file, and they can also
take additional arguments.

list:    List names of the keywords the library/resource contains. Can be
         limited to show only certain keywords by passing optional patterns as
         arguments. Keyword is listed if its name contains any given pattern.
show:    Show library/resource documentation. Can be limited to show only
         certain keywords by passing names as arguments. Keyword is shown if
         its name matches any given name. Special argument `intro` will show
         the library introduction and importing sections.
version: Show library version

Optional patterns given to `list` and `show` are case and space insensitive.
Both also accept `*` and `?` as wildcards.

Examples:

  libdoc Dialogs list
  libdoc SeleniumLibrary list browser
  libdoc Remote::10.0.0.42:8270 show
  libdoc Dialogs show PauseExecution execute*
  libdoc SeleniumLibrary show intro
  libdoc SeleniumLibrary version

Alternative execution
=====================

Libdoc works with all interpreters supported by Robot Framework.
 In the examples above Libdoc is executed as an
installed module, but it can also be executed as a script like
`python path/robot/libdoc.py`.

For more information about Libdoc and other built-in tools, see
http://robotframework.org/robotframework/#built-in-tools.