This file provides a Sphinx extension to include an Entity-Relationship diagram of SQLAlchemy metadata, generated by the 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 :
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 :
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 :
sqlaviz -p neato --unique-relations <pkg.module:metadata> -o node_margin='"0,0"' -f out.dot
This extension can be installed from pypi :
pip install sphinxcontrib-sqlalchemyviz
Add the sphinxcontrib.sqlalchemyviz
to Sphinx's list of extensions on the conf.py
In the .rst file where the table should appear, insert the Sphinx directive provided by this module :
.. 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 |
This Sphinx Extension is made available under the BSD 2-clause License. See the LICENSE file for the full text.