django-spaghetti-and-meatballs 0.4.2
Its a spicy meatball for serving up fresh hot entity-relationship diagrams straight from your django models.
License: MIT
Requires Python: >=3.6,<4.0

django-spaghetti-and-meatballs
==============================

|docs| |travis| |code-climate| |coveralls|

Its a spicy meatball for serving up fresh hot entity-relationship diagrams straight from your django models.


Adding spaghetti to your project
--------------------------------

Install some spaghetti:

.. code-block:: sh

  pip install django-spaghetti-and-meatballs

Add ``"django_spaghetti"`` to your ``INSTALLED_APPS`` setting like this:

.. code-block:: python

  INSTALLED_APPS = [
      ...
      'django_spaghetti',
  ]

Configure your sauce
++++++++++++++++++++

``django-spaghetti-and-meatballs`` takes a few options set in the ``SPAGHETTI_SAUCE``
variable from your projects ``settings.py`` file that make it `extra spicy`:

.. code-block:: python

  SPAGHETTI_SAUCE = {
      'apps': ['auth', 'polls'],
      'show_fields': False,
      'exclude': {'auth': ['user']},
  }

In the above dictionary, the following settings are used:

* ``apps`` is a list of apps you want to show in the graph. If its `not` in here it `won't be seen`.
* ``show_fields`` is a boolean that states if the field names should be shown in the graph or just in the however over. For small graphs, you can set this to `True` to show fields as well, but as you get more models it gets messier.
* ``exclude`` is a dictionary where each key is an ``app_label`` and the items for that key are model names to hide in the graph. 

If its not working as expected make sure your app labels and model names are all **lower case**.


Serve your plate in your urls file
++++++++++++++++++++++++++++++++++

Once you've configured your sauce, make sure you serve up a plate of spaghetti in your ``urls.py`` like so:

.. code-block:: python

    urlpatterns += patterns('',
        url(r'^plate/', include('django_spaghetti.urls')),
    )

A sample platter
----------------

Below is an example image showing the connections between models from the 
`django-reversion <https://github.com/etianen/django-reversion>`_ and 
`django-notifications <https://github.com/django-notifications/django-notifications>`_ 
apps and Django's built-in ``auth`` models.

Colored edges illustrate foreign key relations, with arrows pointing from the defining 
model to the related model, while gray edges illustrate many-to-many relations. 
Different colors signify the different Django apps, and when relations link between 
apps the edges are colored with a gradient.

.. image:: https://cloud.githubusercontent.com/assets/2173174/9053053/a45e185c-3ab2-11e5-9ea0-89dafb7ac274.png

Hovering over a model, gives a pop-up that lists the following information:

* model name
* app label
* The models docstring
* A list of every field, with its field type and its help text (if defined). Unique fields have their name underlined.

This was build with the sauce:

.. code-block:: python

  SPAGHETTI_SAUCE = {
      'apps': ['auth', 'notifications', 'reversion'],
      'show_fields': False,
  }

A complex live-demo
-------------------

To see a complex example, where ``django-spaghetti-and-meatballs`` really shines,
checkout the live version built for the `Aristotle Metadata Registry <http://registry.aristotlemetadata.com/labs/plate/>`_

Testing and developing
----------------------

I like keeping my development environments isolated in docker. You can too. If you want to install `poetry` locally, you can skip this bit.

* Build a container with Pythong and Poetry installed - `docker build . -t spaghetti`
* Run a container for developing `docker run -v "$(realpath .)":/site -w /site -p 8000:8000 -it --rm spaghetti bash`

* Install the dependencies - `poetry install`
* Open a poetry shell - `poetry shell`
* Run the server - `django-admin runserver 0.0.0.0:8000`

If you navigate to `127.0.0.1:8000` should should see the demo app.

.. |docs| image:: https://readthedocs.org/projects/django-spaghetti-and-meatballs/badge/?version=latest
    :target: https://django-spaghetti-and-meatballs.readthedocs.io/en/latest/
    :alt: Documentation Status

.. |code-climate| image:: https://codeclimate.com/github/LegoStormtroopr/django-spaghetti-and-meatballs/badges/gpa.svg
   :target: https://codeclimate.com/github/LegoStormtroopr/django-spaghetti-and-meatballs
   :alt: Code Climate

.. |coveralls| image:: https://coveralls.io/repos/LegoStormtroopr/django-spaghetti-and-meatballs/badge.svg?branch=master&service=github
   :target: https://coveralls.io/github/LegoStormtroopr/django-spaghetti-and-meatballs?branch=master

.. |travis| image:: https://travis-ci.org/LegoStormtroopr/django-spaghetti-and-meatballs.svg?branch=master
    :target: https://travis-ci.org/LegoStormtroopr/django-spaghetti-and-meatballs