Metadata-Version: 1.1
Name: sphinxcontrib-htsql
Version: 0.1.2
Summary: HTSQL extension for Sphinx
Home-page: http://bitbucket.org/prometheus/sphinxcontrib-htsql
Author: Kirill Simonov (Prometheus Research, LLC)
Author-email: xi@resolvent.net
License: BSD
Download-URL: http://pypi.python.org/pypi/sphinxcontrib-htsql
Description: *********************************************************
          ``sphinxcontrib-htsql`` -- HTSQL extension for Sphinx
        *********************************************************
        
        Overview
        ========
        
        ``sphinxcontrib-htsql`` is an extension for embedding HTSQL_ queries
        in Sphinx_ documents.
        
        You can see this extension in action at
        http://htsql.org/doc/overview.html#htsql-in-a-nutshell.  For more
        examples, see ``demo`` directory in the source distribution.
        
        This software is written by Kirill Simonov (`Prometheus Research, LLC`_)
        and released under BSD license.
        
        
        Usage
        =====
        
        To enable this extension, add the following line to ``conf.py``::
        
            extensions.append('sphinxcontrib.htsql')
        
        You also need to specify the address of the HTSQL service::
        
            htsql_root = 'http://demo.htsql.org'
        
        Now you can add HTSQL queries to any Sphinx document using ``htsql``
        directive::
        
            .. htsql:: /school?campus='old'
        
        This directive executes the query and inserts a composite block
        consisting of the query string and the query output in tabular form.
        
        If a query spans many lines, it could be written within the directive
        body::
        
            .. htsql::
        
               /school.define(num_dept := count(department))
                      {code, num_dept}?num_dept>3
        
        If you want to display one query with the output of another query, use
        ``output`` option.  It is useful for describing destructive operations,
        not-yet-implemented features or escaping rules.  You need to quote
        whitespace and special characters manually::
        
            .. htsql:: /school?campus='north'
               :output: /school?campus='south'
        
        Normally, the ``htsql`` directive expects the query to be valid.  Use
        ``error`` option to indicate that the query is invalid and you want to
        show the error message::
        
            .. htsql:: /school{code, title}
               :error:
        
        Normally, the query is rendered with a link leading to the HTSQL
        service.  Use ``no-link`` option to disable this feature::
        
            .. htsql:: /school?exists(department)
               :no-link:
        
        Use ``no-output`` option to render the query, but not the output::
        
            .. htsql:: /school[ns]
               :no-output:
        
        Use ``no-input`` option to render the query output, but not the query
        itself::
        
            .. htsql:: /school[ns]
               :no-input:
        
        Normally, query output is rendered as a table.  Use option ``raw`` to
        render the output unformatted::
        
            .. htsql:: /school[ns]/:json
               :raw:
        
        Use ``cut`` option to truncate the query output up to the given number
        of lines.  This option works both with tabular and raw output::
        
            .. htsql:: /school
               :cut: 3
        
        
        Reference
        =========
        
        Directives
        ----------
        
        ``htsql-root``
            Specifies the address of the HTSQL service.
            
            This directive overrides the ``htsql_root`` configuration parameter
            for the rest of the current document.
        
            This directive has no body and no options.
        
        ``htsql``
            Inserts output of an HTSQL query.
        
            The query could be specified as the parameter of the directive or (for
            multi-line queries) as the directive content.
        
            This directive is rendered as a composite block with two entries:
        
            * A literal block with the query string and a link to the HTSQL
              service.
        
            * A table with the query output.
        
            Options:
        
            ``output``
                A query to use as a source for the output block.
        
            ``error``
                Accept invalid queries and render the error message in the
                output block.
        
            ``no-link``
                Do not link the query block to the HTSQL service.
        
            ``no-input``
                Do not render the query block.
        
            ``no-output``
                Do not render the output block.
        
            ``raw``
                Render the output unformatted.
        
            ``cut``
                Truncate the output to the given number of lines.
        
        Configuration parameters
        ------------------------
        
        ``htsql_root``
            The address of HTSQL service.
        
        CSS classes
        -----------
        
        ``htsql-io``
            Wraps the output of ``htsql`` directive.
        
        ``htsql-input``
            Wraps the query block.
        
        ``htsql-output``
            Wraps the output block.
        
        ``htsql-link``
            Wraps a link to the HTSQL service.
        
        ``htsql-arrow-link``
            Wraps an arrow symbol with a link to the HTSQL service.
        
        
        .. _Sphinx: http://sphinx-doc.org/
        .. _HTSQL: http://htsql.org/
        .. _Prometheus Research, LLC: http://prometheusresearch.com/
        
        
        .. vim: set spell spelllang=en textwidth=72:
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing
Requires: Sphinx
