libdoc

Module implementing the command line entry point for the Libdoc tool.

This module can be executed from the command line using the following approaches::

python -m robot.libdoc
python path/to/robot/libdoc.py

This module also exposes the following public API:

• :func:libdoc_cli function for simple command line tools.
• :func:libdoc function as a high level programmatic API.
• :func:~robot.libdocpkg.builder.LibraryDocumentation as the API to generate :class:~robot.libdocpkg.model.LibraryDoc instances.

Libdoc itself is implemented in the :mod:~robot.libdocpkg package.

libdoc(library_or_resource, outfile, name='', version='', format=None, docformat=None, specdocformat=None, quiet=False)

Executes Libdoc.

:param library_or_resource: Name or path of the library or resource file to be documented. :param outfile: Path to the file where to write outputs. :param name: Custom name to give to the documented library or resource. :param version: Version to give to the documented library or resource. :param format: Specifies whether to generate HTML, XML or JSON output. If this options is not used, the format is got from the extension of the output file. Possible values are 'HTML', 'XML', 'JSON' and 'LIBSPEC'. :param docformat: Documentation source format. Possible values are 'ROBOT', 'reST', 'HTML' and 'TEXT'. The default value can be specified in library source code and the initial default is 'ROBOT'. :param specdocformat: Specifies whether the keyword documentation in spec files is converted to HTML regardless of the original documentation format. Possible values are 'HTML' (convert to HTML) and 'RAW' (use original format). The default depends on the output format. New in Robot Framework 4.0. :param quiet: When true, the path of the generated output file is not printed the console. New in Robot Framework 4.0.

Arguments have same semantics as Libdoc command line options with same names. Run libdoc --help or consult the Libdoc section in the Robot Framework User Guide for more details.

Example::

from robot.libdoc import libdoc

libdoc('MyLibrary.py', 'MyLibrary.html', version='1.0')

Source code in src/robot/libdoc.py

def libdoc(library_or_resource, outfile, name='', version='', format=None,
           docformat=None, specdocformat=None, quiet=False):
    """Executes Libdoc.

    :param library_or_resource: Name or path of the library or resource
        file to be documented.
    :param outfile: Path to the file where to write outputs.
    :param name: Custom name to give to the documented library or resource.
    :param version: Version to give to the documented library or resource.
    :param format: Specifies whether to generate HTML, XML or JSON output.
        If this options is not used, the format is got from the extension of
        the output file. Possible values are ``'HTML'``, ``'XML'``, ``'JSON'``
        and ``'LIBSPEC'``.
    :param docformat: Documentation source format. Possible values are
        ``'ROBOT'``, ``'reST'``, ``'HTML'`` and ``'TEXT'``. The default value
        can be specified in library source code and the initial default
        is ``'ROBOT'``.
    :param specdocformat: Specifies whether the keyword documentation in spec
        files is converted to HTML regardless of the original documentation
        format. Possible values are ``'HTML'`` (convert to HTML) and ``'RAW'``
        (use original format). The default depends on the output format.
        New in Robot Framework 4.0.
    :param quiet: When true, the path of the generated output file is not
        printed the console. New in Robot Framework 4.0.

    Arguments have same semantics as Libdoc command line options with same names.
    Run ``libdoc --help`` or consult the Libdoc section in the Robot Framework
    User Guide for more details.

    Example::

        from robot.libdoc import libdoc

        libdoc('MyLibrary.py', 'MyLibrary.html', version='1.0')
    """
    return LibDoc().execute(
        library_or_resource, outfile, name=name, version=version, format=format,
        docformat=docformat, specdocformat=specdocformat, quiet=quiet
    )

libdoc_cli(arguments=None, exit=True)

Executes Libdoc similarly as from the command line.

:param arguments: Command line options and arguments as a list of strings. Starting from RF 4.0, defaults to sys.argv[1:] if not given. :param exit: If True, call sys.exit automatically. New in RF 4.0.

The :func:libdoc function may work better in programmatic usage.

Example::

from robot.libdoc import libdoc_cli

libdoc_cli(['--version', '1.0', 'MyLibrary.py', 'MyLibrary.html'])

Source code in src/robot/libdoc.py

def libdoc_cli(arguments=None, exit=True):
    """Executes Libdoc similarly as from the command line.

    :param arguments: Command line options and arguments as a list of strings.
        Starting from RF 4.0, defaults to ``sys.argv[1:]`` if not given.
    :param exit: If ``True``, call ``sys.exit`` automatically. New in RF 4.0.

    The :func:`libdoc` function may work better in programmatic usage.

    Example::

        from robot.libdoc import libdoc_cli

        libdoc_cli(['--version', '1.0', 'MyLibrary.py', 'MyLibrary.html'])
    """
    if arguments is None:
        arguments = sys.argv[1:]
    LibDoc().execute_cli(arguments, exit=exit)