Source code for robot.libdoc

#!/usr/bin/env python

#  Copyright 2008-2015 Nokia Networks
#  Copyright 2016-     Robot Framework Foundation
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  See the License for the specific language governing permissions and
#  limitations under the License.

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

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

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

Instead of ``python`` it is possible to use also other Python interpreters.

This module also provides :func:`libdoc` and :func:`libdoc_cli` functions
that can be used programmatically. Other code is for internal usage.

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

import sys
import os

# Allows running as a script. __name__ check needed with multiprocessing:
if 'robot' not in sys.modules and __name__ == '__main__':
    import pythonpathsetter

from robot.utils import Application, seq2str
from robot.errors import DataError
from robot.libdocpkg import LibraryDocumentation, ConsoleViewer

USAGE = """robot.libdoc -- Robot Framework library documentation generator

Version:  <VERSION>

Usage:  python -m robot.libdoc [options] library output_file
   or:  python -m robot.libdoc [options] library list|show|version [names]

Libdoc tool can generate keyword documentation in HTML and XML formats both
for libraries and resource files. HTML format is suitable for humans and
XML specs for RIDE and other tools. 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
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


 -f --format HTML|XML|XML:HTML
                          Specifies whether to generate an HTML or XML output
                          file. The XML:HTML format means generating an XML
                          output file where keyword documentation is converted
                          to HTML regardless of the original documentation
                          format. The default output format is got from the
                          output file extension so that `*.html` -> HTML,
                          `*.xml` -> XML and `*.libspec` -> XML:HTML.
 -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`.
 -n --name name           Sets the name of the documented library or resource.
 -v --version version     Sets the version of the documented library or
 -P --pythonpath path *   Additional locations where to search for libraries
                          and resources.
 -h -? --help             Print this help.

Creating documentation

When creating documentation in HTML or XML format, the output file must be
specified as the second argument after the library/resource name or path.
Output format is got automatically from the output file extension, but it can
also be set explicitly with the `--format` option. The special `*.libspec`
extension automatically enables the XML:HTML format i.e. creates an XML output
file with keyword documentation converted to HTML.


  python -m robot.libdoc src/ doc/MyLibrary.html
  jython -m robot.libdoc MyLibrary.html
  python -m robot.libdoc --name MyLibrary Remote:: MyLibrary.xml
  python -m robot.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.


  python -m robot.libdoc Dialogs list
  python -m robot.libdoc SeleniumLibrary list browser
  python -m robot.libdoc Remote:: show
  python -m robot.libdoc Dialogs show PauseExecution execute*
  python -m robot.libdoc SeleniumLibrary show intro
  python -m robot.libdoc SeleniumLibrary version

Alternative execution

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

For more information about Libdoc and other built-in tools, see

[docs]class LibDoc(Application): def __init__(self): Application.__init__(self, USAGE, arg_limits=(2,), auto_version=False)
[docs] def validate(self, options, arguments): if ConsoleViewer.handles(arguments[1]): ConsoleViewer.validate_command(arguments[1], arguments[2:]) elif len(arguments) > 2: raise DataError('Only two arguments allowed when writing output.') return options, arguments
[docs] def main(self, args, name='', version='', format=None, docformat=None): lib_or_res, output = args[:2] libdoc = LibraryDocumentation(lib_or_res, name, version, self._get_doc_format(docformat)) if ConsoleViewer.handles(output): ConsoleViewer(libdoc).view(output, *args[2:]) else:, self._get_output_format(format, output)) self.console(os.path.abspath(output))
def _get_doc_format(self, format): if not format: return None return self._verify_format('Doc format', format, ['ROBOT', 'TEXT', 'HTML', 'REST']) def _get_output_format(self, format, output): extension = os.path.splitext(output)[1][1:].upper() default = 'XML:HTML' if extension == 'LIBSPEC' else extension return self._verify_format('Format', format or default, ['HTML', 'XML', 'XML:HTML']) def _verify_format(self, type, format, valid): format = format.upper() if format not in valid: raise DataError("%s must be %s, got '%s'." % (type, seq2str(valid, lastsep=' or '), format)) return format
[docs]def libdoc_cli(arguments): """Executes Libdoc similarly as from the command line. :param arguments: Command line arguments as a list of strings. For programmatic usage the :func:`libdoc` function is typically better. It has a better API for that usage and does not call :func:`sys.exit` like this function. Example:: from robot.libdoc import libdoc_cli libdoc_cli(['--version', '1.0', '', 'MyLibraryDoc.html']) """ LibDoc().execute_cli(arguments)
[docs]def libdoc(library_or_resource, outfile, name='', version='', format=None, docformat=None): """Executes Libdoc. :param library_or_resource: Name or path of the library or resource file to be documented. :param outfile: Path 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 or XML output. If this options is not used, the format is got from the extension of the output file. Possible values are ``'HTML'`` and ``'XML'``. :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'``. New in Robot Framework 3.0.3. Arguments have same semantics as Libdoc command line options with same names. Run ``python -m robot.libdoc --help`` or consult the Libdoc section in the Robot Framework User Guide for more details. Example:: from robot.libdoc import libdoc libdoc('', 'MyLibraryDoc.html', version='1.0') """ LibDoc().execute(library_or_resource, outfile, name=name, version=version, format=format, docformat=docformat)
if __name__ == '__main__': libdoc_cli(sys.argv[1:])