Merge pull request #99 from MITx/victor/create_docs

Victor/create docs

common/lib/capa/eia.py

+""" Standard resistor codes.
+http://en.wikipedia.org/wiki/Electronic_color_code
+"""
 E6=[10,15,22,33,47,68]
 E12=[10,12,15,18,22,27,33,39,47,56,68,82]
 E24=[10,12,15,18,22,27,33,39,47,56,68,82,11,13,16,20,24,30,36,43,51,62,75,91]

common/lib/xmodule/capa_module.py

@@ -281,6 +281,7 @@ class Module(XModule):
 
     def answer_available(self):
         ''' Is the user allowed to see an answer?
+        TODO: simplify. 
         '''
         if self.show_answer == '':
             return False

doc/README

+This directory contains some high level documentation for the code.  We should strive to keep it up-to-date, but don't take it as the absolute truth.
+
+A good place to start is 'overview.md'

doc/overview.md

+# Documentation for edX code (mitx repo)
+
+This document explains the general structure of the edX platform, and defines some of the acronyms and terms you'll see flying around in the code.
+
+## Assumptions:
+
+You should be familiar with the following.  If you're not, go read some docs...
+
+ - python
+ - django
+ - javascript
+ - html, xml -- xpath, xslt
+ - css
+ - git
+ - mako templates -- we use these instead of django templates, because they support embedding real python.
+ 
+## Other relevant terms
+
+ - CAPA -- lon-capa.org -- content management system that has defined a standard for online learning and assessment materials.  Many of our materials follow this standard.
+    - TODO: add more details / link to relevant docs.  lon-capa.org is not immediately intuitive.  
+    - lcp = loncapa problem
+
+
+## Parts of the system
+
+  - LMS -- Learning Management System.   The student-facing parts of the system.  Handles student accounts, displaying videos, tutorials, exercies, problems, etc. 
+
+  - CMS -- Course Management System.  The instructor-facing parts of the system.  Allows instructors to see and modify their course, add lectures, problems, reorder things, etc.
+
+  - Askbot -- the discussion forums.  We have a custom fork of this project.  We're also hoping to replace it with something better later.  (e.g. need support for multiple classes, etc)
+
+  - Data.  In the data/ dir.  There is currently a single `course.xml` file that describes an entire course.  Speaking of which...
+
+  - Courses.  A course is broken up into Chapters ("week 1", "week 2", etc).  A chapter is broken up into Sections ("Lecture 1", "Simple Circuits Exercises", "HW1", etc).  A section can contain modules: Problems, Html, Videos, Verticals, or Sequences.
+     - Problems: specified in problem files.  May have python scripts embedded to both generate random parameters and check answers.  Also allows specifying things like tolerance or precision in answers
+     - Html: any html - often description, or links to outside resources
+     - Videos: links to youtube or elsewhere
+     - Verticals: a nesting tag: collect several videos, problems, html modules and display them vertically.
+     - Sequences: a sequence of modules, displayed with a horizontal navigation bar, displaying one component at a time.
+     - see `data/course.xml` for more examples
+
+
+## High Level Entities in the code
+
+### Common libraries 
+
+- x_modules -- generic learning modules. *x* can be sequence, video, template, html, vertical, capa, etc.  These are the things that one puts inside sections in the course structure.  Modules know how to render themselves to html, how to score themselves, and handle ajax calls from the front end. 
+      - x_modules take a 'system context' parameter, which helps isolate xmodules from any particular application, so they can be used in many places. The modules should make no references to Django (though there are still a few left).  The system context knows how to render things, track events, complain about 404s, etc. 
+      - TODO: document the system context interface--it's different in `x_module.XModule.__init__` and in `x_module tests.py` (do this in the code, not here)
+      - in `common/lib/xmodule`
+
+- capa modules -- defines `LoncapaProblem` and many related things.  
+    - in `common/lib/capa`
+
+### LMS 
+
+The LMS is a django site, with root in `lms/`.  It runs in many different environments--the settings files are in `lms/envs`. 
+
+- We use the Django Auth system, including the is_staff and is_superuser flags.  User profiles and related code lives in `lms/djangoapps/student/`.   There is support for groups of students (e.g. 'want emails about future courses', 'have unenrolled', etc) in `lms/djangoapps/student/models.py`.
+
+- `StudentModule` -- keeps track of where a particular student is in a module (problem, video, html)--what's their grade, have they started, are they done, etc.  [This is only partly implemented so far.]
+    - `lms/djangoapps/courseware/models.py`
+
+- Core rendering path:
+  - `lms/urls.py` points to `courseware.views.index`, which gets module info from the course xml file, pulls list of `StudentModule` objects for this user (to avoid multiple db hits).  
+
+  - Calls `render_accordion` to render the "accordion"--the display of the course structure.
+
+  - To render the current module, calls `module_render.py:render_x_module()`, which gets the `StudentModule` instance, and passes the `StudentModule` state and other system context to the module constructor the get an instance of the appropriate module class for this user.
+
+  - calls the module's `.get_html()` method.  If the module has nested submodules, render_x_module() will be called again for each.
+  
+  - ajax calls go to `module_render.py:modx_dispatch()`, which passes it to the module's `handle_ajax()` function, and then updates the grade and state if they changed.
+
+  - [This diagram](https://github.com/MITx/mitx/wiki/MITx-Architecture) visually shows how the clients communicate with problems + modules.
+  
+- See `lms/urls.py` for the wirings of urls to views.  
+
+- Tracking: there is support for basic tracking of client-side events in `lms/djangoapps/track`.  
+
+### Other modules
+
+- Wiki -- in `lms/djangoapps/simplewiki`.  Has some markdown extentions for embedding circuits, videos, etc.
+
+## Testing
+
+See `testing.md`.
+
+## TODO:
+
+- update lms/envs/README.txt
+
+- describe our production environment
+
+- describe the front-end architecture, tools, etc.  Starting point: `lms/static`
+
+---
+Note: this file uses markdown.  To convert to html, run:
+
+    markdown2 overview.md > overview.html

doc/testing.md

+# Testing
+
+Testing is good.  Here is some useful info about how we set up tests--
+
+### Backend code:
+
+- TODO
+
+### Frontend code:
+
+- TODO
+

lms/djangoapps/courseware/module_render.py

@@ -89,6 +89,19 @@ def grade_histogram(module_id):
     return grades
 
 def get_module(user, request, xml_module, module_object_preload, position=None):
+    ''' Get the appropriate xmodule and StudentModule.
+
+    Arguments:
+      - user                  : current django User
+      - request               : current django HTTPrequest
+      - xml_module            : lxml etree of xml subtree for the current module
+      - module_object_preload : list of StudentModule objects, one of which may match this module type and id
+      - position   	      : extra information from URL for user-specified position within module
+
+    Returns:
+      - a tuple (xmodule instance, student module, module type).
+
+    '''
     module_type=xml_module.tag
     module_class=xmodule.get_module_class(module_type)
     module_id=xml_module.get('id') #module_class.id_attribute) or "" 
@@ -184,7 +197,19 @@ def render_x_module(user, request, xml_module, module_object_preload, position=N
     return content
 
 def modx_dispatch(request, module=None, dispatch=None, id=None):
-    ''' Generic view for extensions. This is where AJAX calls go.'''
+    ''' Generic view for extensions. This is where AJAX calls go.
+
+    Arguments:
+
+      - request -- the django request.
+      - module -- the type of the module, as used in the course configuration xml.
+                  e.g. 'problem', 'video', etc
+      - dispatch -- the command string to pass through to the module's handle_ajax call
+           (e.g. 'problem_reset').  If this string contains '?', only pass
+           through the part before the first '?'.
+      - id -- the module id.  Used to look up the student module.
+            e.g. filenamexformularesponse
+    '''
     if not request.user.is_authenticated():
         return redirect('/')
 
@@ -200,6 +225,8 @@ def modx_dispatch(request, module=None, dispatch=None, id=None):
     oldgrade = s.grade
     oldstate = s.state
 
+    # TODO: if dispatch is left at default value None, this will go boom.  What's the correct
+    # behavior?
     dispatch=dispatch.split('?')[0]
 
     ajax_url = settings.MITX_ROOT_URL + '/modx/'+module+'/'+id+'/'

lms/lib/dogfood/README.md

+This is a library for edx4edx, allowing users to practice writing problems.