Merge pull request #24 from edx/rtd_docs

Docs outline

apps/submissions/models.py

 """
-This holds generic submissions and scores information. Is is ignorant of
-workflows, ORA, etc. So the flow is this:
-
-Student submission:
-
-* XBlock creates a Submission
-* submissions app sends a general notification that a submission has happened
-* openassessment can listen for that signal if it wants, or query itself on demand
-* when openassessment is satisfied that it has collected enough information to
-  score the student, it will push that score information back to this app.
-* when the LMS wants to know what raw scores a student has, it calls this app.
-
-Things to consider probably aren't worth the extra effort/complexity in the MVP:
-* Many to Many relations for students-submissions, evaluations-submissions
-* Version ID (this doesn't work until split-mongostore comes into being)
-
+Submission models hold student responses to problems, scores, and a history of
+those scores. It is intended to be a general purpose store that is usable by
+different problem types, and is therefore ignorant of ORA workflow.
 """
 from django.db import models
 from django.utils.timezone import now
@@ -58,7 +45,11 @@ class StudentItem(models.Model):
 class Submission(models.Model):
     """A single response by a student for a given problem in a given course.
 
-    A student may have multiple submissions for the same problem.
+    A student may have multiple submissions for the same problem. Submissions
+    should never be mutated. If the student makes another Submission, or if we
+    have to make corrective Submissions to fix bugs, those should be new
+    objects. We want to keep Submissions immutable both for audit purposes, and
+    because it makes caching trivial.
 
     """
     student_item = models.ForeignKey(StudentItem)

doc/source/api.rst

 .. _api:
 
+Public API
+----------
+
+Every Django application in edx-tim has an `api.py` that is its public
+interface. If you are using one of these applications from the outside, you
+should only import things from that module. The ground rules for api modules
+are:
+
+1. All inputs and outputs must be trivially serializable to JSON. This means
+   `None`, `int`, `float`, `unicode`, `list`, `tuple`, `dict`, and `datetime`.
+2. Returned objects should not have methods or business logic attached to them.
+3. Caller should assume that these calls can be moderately expensive, as they
+   may one day move out of process and become network calls. So calling
+   something a hundred times in a loop should be avoided.
+
 Submissions
------------
+***********
 
 .. automodule:: submissions.api
    :members:
 
 Peer Assessment
----------------
-
-.. automodule:: openassessment.peer.api
-   :members:
+***************
 
 
-Internals
-=========
+Django Apps
+-----------
 
 Submissions
------------
+***********
+
+The Submissions app is responsible for:
+
+1. Storing and retrieving student submissions for answering a given problem.
+2. Storing and retriveing the raw scores assigned to those submissions.
+3. Retrieving the raw scores for all items associated with a particular student
+   in a particular course.
+
+This application is ignorant of the content of submissions, and assumes them to
+simply be opaque unicode strings.
+
+
+Models
+++++++
 .. automodule:: submissions.models
    :members:

doc/source/dev/conventions.rst

-Public Interface
-----------------
-
-Every Django application in edx-tim has an `api.py` that is its public
-interface. If you are using one of these applications from the outside, you
-should only import things from that module. The ground rules for api modules
-are:
-
-1. All inputs and outputs must be trivially serializable to JSON. This means
-   `None`, `int`, `float`, `unicode`, `list`, `tuple`, `dict`, and `datetime`.
-2. Returned objects should not have methods or business logic attached to them.
-3. Caller should assume that these calls can be moderately expensive, as they
-   may one day move out of process and become network calls. So calling
-   something a hundred times in a loop should be avoided.
-
-
-

doc/source/index.rst

@@ -10,9 +10,10 @@ not ready for general use.
 
 Setup
 -----
+::
 
   pip install -r requirements/dev.txt
-
+  pip install -e .
   python manage.py runserver
 
 User Guide
@@ -26,10 +27,6 @@ Author Guide
 Developer Guide
 ---------------
 
-.. toctree::
-   :maxdepth: 2
-
-   dev/conventions
 
 API Documentation
 -----------------