Metadata-Version: 1.0
Name: sphinxcontrib-robotdoc
Version: 0.7.0
Summary: Sphinx extension to embed Robot Framework test cases and 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: 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.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.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
