Add documentation and bump version number to 0.3.0

Author: Mark Gibbs

django_plotly_dash/__init__.py

@@ -1,6 +1,6 @@
 #
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 from .dash_wrapper import DjangoDash
 

django_plotly_dash/models.py

@@ -26,6 +26,9 @@ def save(self, *args, **kwargs):
         return super(StatelessApp, self).save(*args,**kwargs)
 
     def as_dash_app(self):
+        '''
+        Return a DjangoDash instance of the dash application
+        '''
         dd = getattr(self,'_stateless_dash_app_instance',None)
         if not dd:
             dd = get_stateless_by_name(self.app_name)

docs/models_and_state.rst

@@ -1,17 +1,52 @@
 .. _models_and_state:
 
 Django models and application state
-================
+===================================
 
-The ``django_plotly_dash`` application defines a ``DashApp`` model. This represents an instance of application state.
+The ``django_plotly_dash`` application defines ``DashApp`` and ``StatelessApp`` models.
+
+The ``StatelessApp`` model
+----------------------
+
+An instance of the ``StatelessApp`` model represents a single dash application. Every instantiation of
+a ``DjangoDash`` object is registered, and any object that is referenced through the ``DashApp`` model - this
+includes all template access as well as model instances themselves - causes a ``StatelessApp`` model instance to
+be created if one does not already exist.
+
+.. code-block:: python
+
+    class StatelessApp(models.Model):
+        '''
+        A stateless Dash app.
+
+        An instance of this model represents a dash app without any specific state
+        '''
+
+        app_name = models.CharField(max_length=100, blank=False, null=False, unique=True)
+        slug = models.SlugField(max_length=110, unique=True, blank=True)
+
+        def as_dash_app(self):
+            '''
+            Return a DjangoDash instance of the dash application
+            '''
+
+The main role of a ``StatelessApp`` instance is to manage access to the associated ``DjangoDash`` object, as
+expsosed through the ``as_dash_app`` member
+function.
+
+The ``DashApp`` model
+---------------------
+
+An instance of the ``DashApp`` model represents an instance of application state.
 
 .. code-block:: python
 
     class DashApp(models.Model):
         '''
         An instance of this model represents a Dash application and its internal state
         '''
-        app_name = models.CharField(max_length=100, blank=False, null=False, unique=False)
+        stateless_app = models.ForeignKey(StatelessApp, on_delete=models.PROTECT,
+                                          unique=False, null=False, blank=False)
         instance_name = models.CharField(max_length=100, unique=True, blank=True, null=False)
         slug = models.SlugField(max_length=110, unique=True, blank=True)
         base_state = models.TextField(null=False, default="{}")
@@ -36,7 +71,7 @@ The ``django_plotly_dash`` application defines a ``DashApp`` model. This represe
             Add values from the underlying dash layout configuration
             '''
 
-The ``app_name`` corresponds to an application registered through the instantiation of a ``DjangoDash`` object. The ``slug`` field provides a unique identifier
+The ``stateless_app`` references an instance of the ``StatelessApp`` model described above. The ``slug`` field provides a unique identifier
 that is used in URLs to identify the instance of an application, and also its associated server-side state.
 
 The persisted state of the instance is contained, serialised as JSON, in the ``base_state`` variable. This is an arbitrary subset of the internal state of the

docs/template_tags.rst

@@ -15,7 +15,7 @@ a ``DjangoDash`` app within a page as a responsive ``iframe`` element.
 The tag arguments are:
 
 :name = None: The name of the application, as passed to a ``DjangoDash`` constructor.
-:slug = None: The slug of the application instance.
+:slug = None: The slug of an existing ``DashApp`` instance.
 :da = None: An existing ``django_plotly_dash.models.DashApp`` model instance.
 :ratio = 0.1: The ratio of height to width. The container will inherit its width as 100% of its parent, and then rely on
               this ratio to set its height.
@@ -24,4 +24,3 @@ The tag arguments are:
 At least one of ``da``, ``slug`` or ``name`` must be provided. An object identified by ``slug`` will always be used, otherwise any
 identified by ``name`` will be. If either of these arguments are provided, they must resolve to valid objects even if
 not used. If neither are provided, then the model instance in ``da`` will be used.
-