Metadata-Version: 1.0
Name: sphinxcontrib-robotdoc
Version: 0.5.1
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 new Sphinx extension to embed Robot Framework test
        cases and and user keywords into Sphinx documents.
        
        The extension is not a much past *proof-of-concept* yet. Rendering of generated
        documentation may still change in the future, but API should remain backwards
        compatible.
        
        
        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: ../src/my_package/tests/acceptance/my_suite.txt
               :tags: bugs, new
        
            .. robot_keywords:: Keyword title or RegExp.*
               :source: ../src/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``-file. 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 a relative path from
        the current document. (There's no support for package module paths yet.)
        
        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.
        
        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
        
        
        Experimental directives
        -----------------------
        
        ``robot_source`` will embed a complete test suite or resource file with
        syntax highlighting::
        
            .. robot_source::
               :source: ../src/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: ../src/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: ../src/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 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.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
