sphinxcontrib-robotdoc 0.7.0

Sphinx extension to embed Robot Framework test cases and and user keywords into Sphinx documents

Introduction

This package provides a Sphinx-extension to embed Robot Framework test suites, test cases, or user keywords in into Sphinx-documents in spirit of the autodoc Sphinx-extension.

When to use?

Consider not using this package.

This package was created before Robot Framework plain text syntax lexer (highlighting support) was implemented and included into Pygments (>= 1.6rc1). This package was also created before Robot Framework’s built-in libdoc-tool got ReST-syntax support for embedded documentation syntax (>=1.7.5) and Robot Framework got new ReST-support (>= 1.8.2).

Nowadays, the easies way to embed Robot Framework code (plain text syntax) into Sphinx-document should be to simply use the standard .. code-block:: robotframework or include libdoc-generated html with :download:-syntax. Yet, there may be some edge cases where this is the most convenient way to embed external Robot examples into your documentation.

Usage

Add sphinxcontrib_robotdoc into the extensions list of your Sphinx configuration (conf.py):

extensions = [
    "sphinxcontrib_robotdoc",
]

Embed test cases and user keywords into your documentation with the following custom Docutils-directives:

.. robot-tests:: Test case title or RegExp.*
   :source: my_package:tests/acceptance/my_suite.robot
   :tags: bugs, new

.. robot-keywords:: Keyword title or RegExp.*
   :source: my_package:tests/acceptance/my_suite.txt

Both directives (robot-tests and robot-keywords) take a regular expression as their main option (or content in Docutils’ terms) to filter the embeded test cases or keywords found from the given source-resource (or relative path). If no regular expression is given, all found tests or keywords will be embedded (like having .* as the default).

Path given to the mandatory source-option must be either be a package resources (using syntax package_name:resource/path/in/package) or a relative path from the current document.

The test case directive (robot-tests) accepts also an option tags, which is optional. It should inclue a comma separated list of the tags to be used when filtering the tests to be embedded.

Both directives take an optional style-option. When style is set to expanded the output will include headings such as the table name and test case or keyword name. When style is set to minimal the output will include only the target documentation strings without any robot syntax.

Please, note that he documentation found from the embedded test is parsed using Docutils, as a part of the target document. This differs from Robot Framework’s own documentation tools, which expect its own custom markup.

Other directives

robot-source will embed a complete test suite or resource file with syntax highlighting:

.. robot-source::
   :source: my_package:tests/acceptance/my_suite.txt

robot-settings will embed a syntax highlighted settings table (with documentation parsed as reStructuredText) for a test suite a resource file:

.. robot-settings::
   :source: my_package:tests/acceptance/my_suite.txt

robot-variables will embed a syntax highlighted variables table (with documentation parsed as reStructuredText) for a test suite a resource file:

.. robot-variables::
   :source: my_package:tests/acceptance/my_suite.txt

Also directives robot-settings and robot-variables take an optional style-option. When style is set to expanded the output will include the table name.

LaTeX output

LaTeX output is based on Pygments LatexFormatter, which requires custom style definitions to be injeced into latex document preamble. That’s done by default, but when Sphinx latex_preamble setting is set manually, it should include the following:

from pygments.formatters import LatexFormatter

latex_elements['latex_preamble'] = '''\
\usepackage{fancyvrb}
\usepackage{color}
''' + LatexFormatter().get_style_defs()

Changelog

0.7.0 (2013-10-16)

• Rename directives to robot-source, robot-settings, robot-variables, robot-tests and robot-keywords, but keep the old directives for backwards compatibility.

0.6.0 (2013-09-28)

• Add ‘minimal’ style for keywords directive to show keywords without their step definitions [Asko Soukka]

0.5.1 (2013-08-13)

• Fix bug where multiline documentation in settings-part was not completely included [Pawel Sabat]

0.5.0 (2013-05-17)

• Add support for resolving ‘package:filename.robot’-paths using pkg_resources.resource_filename-method [Asko Soukka]

• Fix bug where source directive resulted escaped html markup [Asko Soukka]

0.4.1 (2013-03-24)

• Add Pygments-formatted output also for LaTex output [fixes #4]

0.4.0 (2013-03-10)

• Add new directives robot_source, robot_settings and robot_variables

• Fix relative path issue [fixes #2]

• Refactor and add support for ForLoop-nodes [fixes #1]

• Add align for BDD-keywords

• Add syntax highlighting

0.3.4 (2012-10-21)

• Fixed to use correct title style for test case and keyword titles.

0.3.3 (2012-10-21)

• Fixed a bug where an empty/missing tags option is not parsed correctly.

0.3.2 (2012-10-20)

• Refactored to use Docutils’ nested_parse instead of publish_string (no more lxml and some support for inter-linking).

0.3.1 (2012-10-18)

• Refactored to parse test/keyword documentation with docutils.core.publish_string (and append them as raw nodes) instead of trying to parse them into sphinx document tree.

0.3.0 (2012-10-18)

• Added support for inline rst in test and keyword documentations.

• Added support for tags.

• Added alternative source option as an alias for suite option in tests.

• Added alternative source and resource options as an alias for suite option in keywords.

• Fixed to filter comment lines from steps.

0.2.0 (2012-10-14)

• Fixed node adapters to return section instead of topics.

0.1.1 (2012-10-14)

• Fixed parsing of resource-only files for keywords.

0.1.0 (2012-10-14)

• Proof of concept.