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