Metadata-Version: 2.1
Name: metapensiero.sphinx.autodoc-sa
Version: 2.1
Summary: Autodoc extension to pretty print canned SA queries
Home-page: https://bitbucket.org/lele/metapensiero.sphinx.autodoc_sa
Author: Lele Gaifax
Author-email: lele@metapensiero.it
License: GPLv3+
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Classifier: Framework :: Sphinx :: Extension
Description-Content-Type: text/x-rst
Requires-Dist: setuptools
Requires-Dist: sphinx
Requires-Dist: sqlalchemy
Provides-Extra: dev
Requires-Dist: metapensiero.tool.bump-version ; extra == 'dev'
Requires-Dist: readme-renderer ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'

.. -*- coding: utf-8 -*-
.. :Project:   metapensiero.sphinx.autodoc_sa -- Autodoc extension to pretty print canned SA queries
.. :Created:   Sat 14 Jan 2017 10:34:19 CET
.. :Author:    Lele Gaifax <lele@metapensiero.it>
.. :License:   GNU General Public License version 3 or later
.. :Copyright: © 2017, 2018 Lele Gaifax
..

================================
 metapensiero.sphinx.autodoc_sa
================================

Autodoc extension to pretty print canned SA queries
===================================================

 :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.

__ http://www.sphinx-doc.org/
__ http://www.sqlalchemy.org/
__ http://www.sphinx-doc.org/en/1.5.1/ext/autodoc.html?highlight=autoclass#directive-automodule

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``.

__ http://docs.sqlalchemy.org/en/rel_1_1/faq/sqlexpressions.html#how-do-i-render-sql-expressions-as-strings-possibly-with-bound-parameters-inlined

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.

__ https://sqlparse.readthedocs.io/en/latest/api/#sqlparse.format

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'

__ http://pygments.org/docs/lexers/#lexers-for-various-sql-dialects-and-related-interactive-sessions

If you are using ``PostgreSQL``, you may prefer using the `pglast`__ SQL prettifier over the
default one based on ``sqlparse``::

  autodoc_sa_prettifier = 'pglast'

__ https://pypi.org/project/pglast


.. -*- coding: utf-8 -*-

Changes
-------

2.1 (2019-03-31)
~~~~~~~~~~~~~~~~

* Minor tweak for compatibility with recently released Sphinx 2.0


2.0 (2018-06-16)
~~~~~~~~~~~~~~~~

.. important:: Given that the PostgreSQL-specific prettifier has been renamed from ``pg_query``
               to ``pglast``, I opted to reflect the fact on the value of the
               ``autodoc_sa_prettifier`` option: if you were using that tool, you must change
               it to ``pglast``.

               Sorry for the inconvenience.


1.7 (2018-05-24)
~~~~~~~~~~~~~~~~

* Avoid prettification of BindParameters


1.6 (2018-05-23)
~~~~~~~~~~~~~~~~

* Use Sphinx 1.7+ API to install the extension


1.5 (2017-08-10)
~~~~~~~~~~~~~~~~

* New option ``autodoc_sa_prettifier_options`` to pass arbitrary keyword options to the
  prettifier function


1.4 (2017-08-09)
~~~~~~~~~~~~~~~~

* Replace the dynamic argument placeholders injected by SA with their literal values, leaving
  the developer's explicit bindparams alone


1.3 (2017-08-08)
~~~~~~~~~~~~~~~~

* Handle also the `pglast`__ SQL prettifier

* New options, ``autodoc_sa_prettifier`` and ``autodoc_pygments_lang``

__ https://pypi.org/project/pglast


1.2 (2017-03-22)
~~~~~~~~~~~~~~~~

* Minor tweak, no externally visible changes


1.1 (2017-01-17)
~~~~~~~~~~~~~~~~

* First release on PyPI


1.0 (unreleased)
~~~~~~~~~~~~~~~~

* Polished, tested and extended to support class' attributes as well

* Extracted from metapensiero.sphinx.patchdb


