sphinxcontrib-sqltable

sphinxcontrb-sqltable is an extension to Sphinx to allow authors to embed SQL statements in source documents and produce tabular output in rendered documents.

Features

  1. Supports all databases accessible via SQLAlchemy.

  2. Supports global and query-specific database connection strings.

Details

Examples

The following examples use a SQLite database containing:

CREATE TABLE users (
       name  text,
       email text
       );

INSERT INTO users (name, email) VALUES ('John', 'john@example.com');
INSERT INTO users (name, email) VALUES ('Jane', 'jane@example.com');
INSERT INTO users (name, email) VALUES ('Bobby', 'bobby@example.com');
INSERT INTO users (name, email) VALUES ('Suzy', 'suzy@example.com');

Local Connection String

Use the connection_string option to specify the database to be used for a single query.

.. sqltable:: List of Users
   :connection_string: sqlite:////tmp/sampledata.db

   select name as 'Name', email as 'E-mail' from users
   order by Name asc

produces this table:

List of Users

Name

E-mail

Bobby

bobby@example.com

Jane

jane@example.com

John

john@example.com

Suzy

suzy@example.com

Missing Connection String

Leaving out the connection_string option produces an error:

.. sqltable:: List of Users

   select name as 'Name', email as 'E-mail' from users
   order by Name asc

results in

$ sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.1.2
Initializing SQLTable
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
Connecting to sqlite:///sampledata.db
Running query u"select name as 'Name', email as 'E-mail' from users\norder by Name asc"

.../docs/example.rst:45: ERROR: No connection_string or sqltable_connection_string was specified for sqltable

Installation

Installing sphinxcontrib-sqltable

  1. Install the extension with pip: pip install sphinxcontrib-sqltable

Configuration

  1. Add 'sphinxcontrib.sqltable' to the extensions list in conf.py.

extensions = [ 'sphinxcontrib.sqltable' ]
  1. Set sqltable_connection_string in conf.py to point to the database to be used for the queries. See also Configuration Options.

Configuration Options

Global Options

These options can be set in conf.py along with the other Sphinx configuration settings.

sqltable_connection_string

String specifying the default database to be used for queries, in the format expected by SQLAlchemy.

Directive Options

These options can be set each time the sqltable directive is used.

widths

A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns).

class

Set a “classes” attribute value on the doctree element generated by the directive. Useful for controlling style with CSS.

name

Add text to the “names” attribute of the doctree element generated by the directive. This allows hyperlink references to the element using text as reference name.

connection_string

String specifying the database to be used for queries, in the format expected by SQLAlchemy. Overrides any value of sqltable_connection_string set in the conf.py.

Developers

If you would like to contribute to sphinxcontrib.sqltable directly, these instructions should help you get started. Patches, bug reports, and feature requests are all welcome through the Github. Contributions in the form of patches or pull requests are easier to integrate and will receive priority attention.

Building Documentation

The documentation for sphinxcontrib.sqltable is written in reStructuredText and converted to HTML using Sphinx. The build itself is driven by make. You will need the following packages in order to build the docs:

  • Sphinx

  • docutils

  • sphinxcontrib.sqltable

Once all of the tools are installed into a virtualenv using pip, run make html to generate the HTML version of the documentation.

Release History

2.0.0

  • Drop python 2 support.

  • Fix documentation build on readthedocs.org.

1.1.0

  • Use pbr for packaging.

1.0

  • First public release.