Update docs (#12)

* Automatically update docs' version string from quade module

* Autodoc models

* Remove redundant(?) directive

* Use fully-qualified name

* Reorder the Django models

* Add details to the Scenario docstring

* Markup docstrings with object description directives

docs/conf.py

@@ -18,8 +18,16 @@
 
 import os
 import sys
+sys.path.insert(0, os.path.abspath('../example'))
 sys.path.insert(0, os.path.abspath('../src/quade'))
 
+import django
+import quade
+
+
+os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
+django.setup()
+
 
 # -- General configuration ------------------------------------------------
 
@@ -57,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.0.1'
+version = '.'.join(quade.__version__.split('.')[:2])
 # The full version, including alpha/beta/rc tags.
-release = u'0.0.1'
+release = quade.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -82,9 +90,12 @@
 
 # -- Options for HTML output ----------------------------------------------
 
+# Capitalize "Documentation" (compared to the default title)
+html_title = '{} {} Documentation'.format(project, release)
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
+
 html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme

docs/index.rst

@@ -13,5 +13,5 @@ Dive in with our :doc:`quickstart`!
 
    quickstart
    installation
+   models
    settings
-

docs/models.rst

@@ -0,0 +1,5 @@
+Models
+======
+
+.. automodule:: quade.models
+   :members: Scenario, Record, RecordedObject

docs/quickstart.rst

@@ -32,7 +32,7 @@ Quickstart
 
     QUADE = quade.settings(fixtures_file='fixtures')
 
-4. Enter the Django shell and create a ``Scenario`` that uses this fixture::
+4. Enter the Django shell and create a :class:`.Scenario` that uses this fixture::
 
     from quade.models import Scenario
     Scenario.objects.create(
@@ -45,4 +45,4 @@ Quickstart
 5. Start your project's webserver and visit the main Quade page. You will be able to generate new
    users on demand by selecting the "Single User" scenario and executing it.
 
-6. Begin creating your own fixtures and Scenarios!
+6. Begin creating your own fixtures and :class:`Scenarios <.Scenario>`!

docs/settings.rst

@@ -15,5 +15,5 @@ Available Settings
 Convenience Classes and Methods
 -------------------------------
 
-.. automodule:: settings
+.. automodule:: quade.settings
    :members:

src/quade/models.py

@@ -24,6 +24,10 @@ def active(self):
 class Scenario(m.Model):
     """
     A specific scenario that QA tests will be run against.
+
+    The heart of a ``Scenario`` is the `config` attribute. `config` is a list of several fixtures,
+    possibly with arguments, which are executed sequentially to create and modify objects in the
+    database.
     """
 
     class Meta:
@@ -74,7 +78,7 @@ def save(self, *args, **kwargs):
 
 class Record(m.Model):
     """
-    A record of setting up, and possibly executing, a particular test scenario.
+    A record of setting up, and possibly executing, a particular :class:`Scenario`.
     """
 
     class Meta:
@@ -124,8 +128,8 @@ def _fail(self, exception):
 @python_2_unicode_compatible
 class RecordedObject(m.Model):
     """
-    A joiner table for creating a generic many-to-many relation between Records and any other
-    objects.
+    A joiner table for creating a generic many-to-many relation between :class:`Records <Record>`
+    and any other objects.
     """
 
     class Meta: