Metadata-Version: 2.0
Name: sphinxcontrib-sqlalchemyviz
Version: 0.3
Summary: Sphinx SQLAlchemyViz extension
Home-page: https://github.com/chintal/sphinxcontrib-sqlalchemyviz
Author: Chintalagiri Shashank
Author-email: shashank@chintal.in
License: BSD
Download-URL: https://github.com/chintal/sphinxcontrib-sqlalchemyviz
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Framework :: Sphinx :: Extension
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Dist: SQLAlchemyViz
Requires-Dist: Sphinx (>=0.6)

SQLAlchemyViz Sphinx Extension
==============================

This file provides a Sphinx extension to include an Entity-Relationship
diagram of SQLAlchemy metadata, generated by the
`SQLAlchemyViz <https://pypi.python.org/pypi/SQLAlchemyViz>`_ package. This is
a highly unpolished extension which does almost no heavy lifting, and not
portable across platforms. The SQLALchemyViz package converts the SQLAlchemy
metadata object into a dot file. The extension then uses POSIX/Linux tools
via python's subprocess mechanisms to improve the layout of the graph.

To achieve the same effect directly from the shell, the relevant commands would
be :

.. code-block:: bash

    sqlaviz --unique-relations --show-constraints <pkg.module:metadata> -f out.dot
    ccomps -x out.dot | dot | gvpack -array3 | neato -Tpng -n2 -o out.png


.. note::

    Some metadata models make SQLAlchemyViz hit a bug in graphviz/dot. In
    order to work around this, the rendering commands have been switched
    in v0.2 to :

    .. code-block:: bash

        sqlaviz -p neato --unique-relations <pkg.module:metadata> -f out.dot
        ccomps -x out.dot | dot | gvpack -array3 | neato -Tpng -n2 -o out.png

    This change will hopefully be rolled back at some point, once the
    underlying bugs have been resolved.

.. note::

    Recent update(s) to SQLAlchemyViz / pydot creates a syntax error in the
    generated .dot file. This is worked around by changing the sqlaviz command
    in v0.3 to :

    .. code-block:: bash

        sqlaviz -p neato --unique-relations <pkg.module:metadata> -o node_margin='"0,0"' -f out.dot


Installation & Usage
--------------------

This extension can be installed from pypi :

    .. code-block:: bash

        pip install sphinxcontrib-sqlalchemyviz

In the .rst file where the table should appear, insert the Sphinx
directive provided by this module :

    .. code-block:: rest

        .. .. sqlaviz::
            :metadataobject: full.importable.path.of.metadata

For a basic usage example, see:

:Python: https://github.com/chintal/tendril/blob/master/tendril/utils/db.py#L201
:Generated: http://tendril.chintal.in/doc/apidoc/tendril.utils.db/#tendril.utils.db.metadata


License
-------

This Sphinx Extension is made available under the BSD 2-clause License. See
the LICENSE file for the full text.



