Metadata-Version: 2.0
Name: sphinxcontrib-robotdoc
Version: 0.10.0
Summary: Sphinx extension to embed Robot Framework test cases and user keywords into Sphinx documents
Home-page: https://github.com/datakurre/sphinxcontrib-robotdoc/
Author: Asko Soukka
Author-email: asko.soukka@iki.fi
License: GPL
Description-Content-Type: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Requires-Dist: setuptools
Requires-Dist: sphinx
Requires-Dist: pygments (>=1.6rc1)
Requires-Dist: robotframework (>=2.7.1)

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.

.. _Robot Framework: http://pypi.python.org/pypi/robotframework


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.10.0 (2018-05-11)
-------------------

- Add to release as universal wheel
  [Asko Soukka]
- Changes for newer sphinx versions
  [Stein Heselmans]


0.9.1 (2017-05-31)
------------------

- Allow for tabs in documentation of robot files
  [Stein Heselmans]


0.9.0 (2017-05-21)
------------------

- Python 3 support
  [Stein Heselmans]


0.8.0 (2015-10-09)
------------------

- Change to separate tags with double space instead comma
  [Asko Soukka]


0.7.3 (2014-06-13)
------------------

- Added documentation generating for test-cases, keywords tags in expanded style.
  [Tomasz Kolek]


0.7.2 (2013-10-19)
------------------

- Fix to use RobotFrameworkLexer from Pygments. Require Pygments >= 1.6rc1
  [Asko Soukka]
- Drop dependency on robotframeworklexer, because it's included in Pygments
  [Asko Soukka]

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.


