README

*********************************************************
  ``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: