.. -*- 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
Raw data
{
"_id": null,
"home_page": "https://bitbucket.org/lele/metapensiero.sphinx.autodoc_sa",
"name": "metapensiero.sphinx.autodoc-sa",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Lele Gaifax",
"author_email": "lele@metapensiero.it",
"download_url": "https://files.pythonhosted.org/packages/c2/98/cb64f463f30fd387e68c60926847296f8c53e074fdbc45e4fa8bec15b57c/metapensiero.sphinx.autodoc_sa-2.1.tar.gz",
"platform": "",
"description": ".. -*- coding: utf-8 -*-\n.. :Project: metapensiero.sphinx.autodoc_sa -- Autodoc extension to pretty print canned SA queries\n.. :Created: Sat 14 Jan 2017 10:34:19 CET\n.. :Author: Lele Gaifax <lele@metapensiero.it>\n.. :License: GNU General Public License version 3 or later\n.. :Copyright: \u00a9 2017, 2018 Lele Gaifax\n..\n\n================================\n metapensiero.sphinx.autodoc_sa\n================================\n\nAutodoc extension to pretty print canned SA queries\n===================================================\n\n :author: Lele Gaifax\n :contact: lele@metapensiero.it\n :license: GNU General Public License version 3 or later\n\nThis is a very simple extension to Sphinx__ that injects the ability to recognize and pretty\nprint SQLAlchemy__ statements into its `automodule`__ and autoclass directives.\n\n__ http://www.sphinx-doc.org/\n__ http://www.sqlalchemy.org/\n__ http://www.sphinx-doc.org/en/1.5.1/ext/autodoc.html?highlight=autoclass#directive-automodule\n\nTo use it, first of all you must register the extension within the Sphinx environment, adding\nthe full name of the package to the ``extensions`` list in the file ``conf.py``, for example::\n\n # Add any Sphinx extension module names here, as strings.\n extensions = ['metapensiero.sphinx.autodoc_sa']\n\nWithout further settings it uses the default SQLAlchemy `stringification strategy`__, but you\ncan explicitly choose the right *dialect* by setting ``autodoc_sa_dialect`` to a string\ncontaining its fully qualified name, for example::\n\n autodoc_sa_dialect = 'sqlalchemy.dialects.postgresql.dialect'\n\nOtherwise, you can set it using the ``-D`` option of the ``sphinx-build`` command, e.g. adding\n``-D autodoc_sa_dialect=my.own.dialect`` to the ``SPHINXOPTS`` of the Makefile created by\n``sphinx-quickstart``.\n\n__ http://docs.sqlalchemy.org/en/rel_1_1/faq/sqlexpressions.html#how-do-i-render-sql-expressions-as-strings-possibly-with-bound-parameters-inlined\n\nAt this point, any documented SQLAlchemy core statement or ORM query, appearing either at the\nmodule level or as a class attribute, will be *compiled* into SQL, beautified using\n`sqlparse.format()`__ and added to the documentation wrapped within a ``code-block:: sql``\ndirective.\n\n__ https://sqlparse.readthedocs.io/en/latest/api/#sqlparse.format\n\nIf you chose a specific SQLAlchemy dialect, by any chance you may want to select the right\nPygments lexer__ to adjust the highlighting rules, instead of the default ``sql``::\n\n autodoc_sa_pygments_lang = 'postgresql'\n\n__ http://pygments.org/docs/lexers/#lexers-for-various-sql-dialects-and-related-interactive-sessions\n\nIf you are using ``PostgreSQL``, you may prefer using the `pglast`__ SQL prettifier over the\ndefault one based on ``sqlparse``::\n\n autodoc_sa_prettifier = 'pglast'\n\n__ https://pypi.org/project/pglast\n\n\n.. -*- coding: utf-8 -*-\n\nChanges\n-------\n\n2.1 (2019-03-31)\n~~~~~~~~~~~~~~~~\n\n* Minor tweak for compatibility with recently released Sphinx 2.0\n\n\n2.0 (2018-06-16)\n~~~~~~~~~~~~~~~~\n\n.. important:: Given that the PostgreSQL-specific prettifier has been renamed from ``pg_query``\n to ``pglast``, I opted to reflect the fact on the value of the\n ``autodoc_sa_prettifier`` option: if you were using that tool, you must change\n it to ``pglast``.\n\n Sorry for the inconvenience.\n\n\n1.7 (2018-05-24)\n~~~~~~~~~~~~~~~~\n\n* Avoid prettification of BindParameters\n\n\n1.6 (2018-05-23)\n~~~~~~~~~~~~~~~~\n\n* Use Sphinx 1.7+ API to install the extension\n\n\n1.5 (2017-08-10)\n~~~~~~~~~~~~~~~~\n\n* New option ``autodoc_sa_prettifier_options`` to pass arbitrary keyword options to the\n prettifier function\n\n\n1.4 (2017-08-09)\n~~~~~~~~~~~~~~~~\n\n* Replace the dynamic argument placeholders injected by SA with their literal values, leaving\n the developer's explicit bindparams alone\n\n\n1.3 (2017-08-08)\n~~~~~~~~~~~~~~~~\n\n* Handle also the `pglast`__ SQL prettifier\n\n* New options, ``autodoc_sa_prettifier`` and ``autodoc_pygments_lang``\n\n__ https://pypi.org/project/pglast\n\n\n1.2 (2017-03-22)\n~~~~~~~~~~~~~~~~\n\n* Minor tweak, no externally visible changes\n\n\n1.1 (2017-01-17)\n~~~~~~~~~~~~~~~~\n\n* First release on PyPI\n\n\n1.0 (unreleased)\n~~~~~~~~~~~~~~~~\n\n* Polished, tested and extended to support class' attributes as well\n\n* Extracted from metapensiero.sphinx.patchdb",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Autodoc extension to pretty print canned SA queries",
"version": "2.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "08729eba9e858f065f87f461bf44ba46",
"sha256": "d4429a394ffe239b5f276d1bb0c8080a0b8f6d774819fb1e230318b31298d2fc"
},
"downloads": -1,
"filename": "metapensiero.sphinx.autodoc_sa-2.1.tar.gz",
"has_sig": false,
"md5_digest": "08729eba9e858f065f87f461bf44ba46",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9588,
"upload_time": "2019-03-31T08:25:30",
"upload_time_iso_8601": "2019-03-31T08:25:30.024788Z",
"url": "https://files.pythonhosted.org/packages/c2/98/cb64f463f30fd387e68c60926847296f8c53e074fdbc45e4fa8bec15b57c/metapensiero.sphinx.autodoc_sa-2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-03-31 08:25:30",
"github": false,
"gitlab": false,
"bitbucket": true,
"bitbucket_user": "lele",
"bitbucket_project": "metapensiero.sphinx.autodoc_sa",
"lcname": "metapensiero.sphinx.autodoc-sa"
}
JSON