-
- GitHub
- GitLab
- Bitbucket
-
By logging in you accept
our terms of service
and privacy policy
Autodoc extension to pretty print canned SA queries
pip install metapensiero.sphinx.autodoc-sa==2.2.dev2
author: Lele Gaifax contact: lele@metapensiero.it license: GNU General Public License version 3 or later
This is a very simple extension to Sphinx that injects the ability to recognize and pretty print SQLAlchemy statements into its automodule and autoclass directives.
To use it, first of all you must register the extension within the Sphinx environment, adding
the full name of the package to the extensions list in the file conf.py, for example:
# Add any Sphinx extension module names here, as strings. extensions = ['metapensiero.sphinx.autodoc_sa']
Without further settings it uses the default SQLAlchemy stringification strategy, but you
can explicitly choose the right dialect by setting autodoc_sa_dialect to a string
containing its fully qualified name, for example:
autodoc_sa_dialect = 'sqlalchemy.dialects.postgresql.dialect'
Otherwise, you can set it using the -D option of the sphinx-build command, e.g. adding
-D autodoc_sa_dialect=my.own.dialect to the SPHINXOPTS of the Makefile created by
sphinx-quickstart.
At this point, any documented SQLAlchemy core statement or ORM query, appearing either at the
module level or as a class attribute, will be compiled into SQL, beautified using
sqlparse.format() and added to the documentation wrapped within a code-block:: sql
directive.
If you chose a specific SQLAlchemy dialect, by any chance you may want to select the right
Pygments lexer to adjust the highlighting rules, instead of the default sql:
autodoc_sa_pygments_lang = 'postgresql'
If you are using PostgreSQL, you may prefer using the pglast SQL prettifier over the
default one based on sqlparse:
autodoc_sa_prettifier = 'pglast'
The Tidelift Subscription provides access to a continuously curated stream of human-researched and maintainer-verified data on open source packages and their licenses, releases, vulnerabilities, and development practices.
Learn more →Login to resync this project