Merge pull request #15 from edx/submissions_docs

Docs outline

README.md

-This is an initial prototype for redesigning Peer Grading and general Open Ended Submission Evaluation.
-
-Installation
-------------
-
-The intent of this project is to be installed as a plugin for the edx-platform. Use pip to install edx-tim against the
-edx-platform's list of requirements. Refer to the XBlock documentation for more details on installing new XBlocks
-against edx-platform.
-
-License
--------
-
-The code in this repository is licensed under version 3 of the AGPL unless
-otherwise noted.
-
-Please see ``LICENSE.txt`` for details.
-
-Documentation
-------------
-
-This project currently the home of the peer grading module. edx-tim must be installed against the edx-platform for full
-functionality. The goal of the edx-tim project is to build a clean, stable, scalable set of grading modules.  All work
-on this framework should be designed to be implementation independent at the schema level, such that submissions can
-be resubmitted against any number of different grading modules.
-
-How to Contribute
------------------
-
-The edx-tim repository is now public. External pull requests may be limited currently, as the project is in initial
-phases of development.
-
-Please read [How To Contribute](https://github.com/edx/edx-platform/wiki/How-To-Contribute) for details.
-
-Reporting Security Issues
--------------------------
-
-Please do not report security issues in public. Please email security@edx.org
-
-Mailing List and IRC Channel
-----------------------------
-
-You can discuss this code on the [edx-code Google Group](https://groups.google.com/forum/#!forum/edx-code) or in the
-`edx-code` IRC channel on Freenode.

README.rst

+This is an initial prototype for redesigning Peer Grading and general Open Ended
+Submission Evaluation. This project is in the early stages of development and is
+not ready for general use.
+
+Installation
+============
+
+The intent of this project is to be installed as Django apps that will be
+included in `edx-platform <https://github.com/edx/edx-platform>`_. To install
+for development purposes, run::
+
+  pip install -r requirements/dev.txt
+
+License
+=======
+
+The code in this repository is licensed under version 3 of the AGPL unless
+otherwise noted.
+
+Please see ``LICENSE.txt`` for details.
+
+How to Contribute
+=================
+
+Due to the very early stage of development we're at, we are not accepting
+contributions at this time. Large portions of the API can change with little
+notice.
+
+Reporting Security Issues
+=========================
+
+Please do not report security issues in public. Please email security@edx.org
+
+Mailing List and IRC Channel
+============================
+
+You can discuss this code on the
+`edx-code Google Group <https://groups.google.com/forum/#!forum/edx-code>`_ or
+in the `edx-code` IRC channel on Freenode.

apps/submissions/models.py

@@ -3,6 +3,7 @@ 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
 * openresponse can listen for that signal if it wants, or query itself on demand
@@ -74,6 +75,9 @@ class Submission(models.Model):
 class Score(models.Model):
     """What the user scored for a given StudentItem.
 
+    TODO: Make a ScoreHistory that has more detailed log information so that we
+          can reconstruct what the state was at a given point in time and debug
+          more easily.
     """
     student_item = models.ForeignKey(StudentItem)
     submission = models.ForeignKey(Submission, null=True)

doc/source/api.rst

+.. _api:
+
+Submissions
+-----------
+
+.. automodule:: submissions.api
+   :members:
+
+Peer Assessment
+---------------
+
+.. automodule:: openassessment.peer.api
+   :members:
+
+
+Internals
+=========
+
+Submissions
+-----------
+.. automodule:: submissions.models
+   :members:

doc/source/conf.py

@@ -13,6 +13,8 @@
 
 import sys, os
 
+import sphinx_rtd_theme
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -24,9 +26,9 @@ import sys, os
 #needs_sphinx = '1.0'
 root = os.path.abspath('../..')
 
+sys.path.append(os.path.join(root, "apps"))
 sys.path.append(root)
-sys.path.append(os.path.join(root, "common_grading"))
-sys.path.append(os.path.join(root, "peer_grading"))
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.base")
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -96,7 +98,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -104,7 +106,7 @@ html_theme = 'default'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

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

 .. edx-tim documentation master file, created by
    sphinx-quickstart on Fri Jan 17 08:32:59 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to edx-tim's documentation!
-===================================
+edx-tim: Open Response Assessment (v2)
+======================================
 
-Contents:
+This is an initial prototype for redesigning Peer Grading and general Open Ended
+Submission Evaluation. This project is in the early stages of development and is
+not ready for general use.
+
+Setup
+-----
+
+  pip install -r requirements/dev.txt
+
+  python manage.py runserver
+
+User Guide
+----------
+
+
+Author Guide
+------------
+
+
+Developer Guide
+---------------
 
 .. toctree::
    :maxdepth: 2
-.. automodule:: api
-   :members:
 
+   dev/conventions
+
+API Documentation
+-----------------
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api
 

requirements/dev.txt

+# Grab everything in test (which pulls everything in base)
+-r test.txt
+
+# Debug tools
+bpython==0.12
+django-debug-toolbar==0.11.0
+sqlparse==0.1.10
+
+# Doc generation
+docutils==0.11
+Jinja2==2.7.1
+MarkupSafe==0.18
+Pygments==1.6
+Sphinx==1.2
+sphinx-rtd-theme==0.1.5
+sphinxcontrib-napoleon==0.2.3
\ No newline at end of file

requirements/test.txt

+# Grab everything in base requirements
+-r base.txt
+
 django-nose==1.2
 mock==1.0.1
 nose==1.3.0