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