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¶
Supports all databases accessible via SQLAlchemy.
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:
Name |
|
---|---|
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¶
Install the extension with pip:
pip install sphinxcontrib-sqltable
Configuration¶
Add
'sphinxcontrib.sqltable'
to theextensions
list inconf.py
.
extensions = [ 'sphinxcontrib.sqltable' ]
Set
sqltable_connection_string
inconf.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 theconf.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.