schoolutils / docs /

Full commit
* Tasks 
** WAITING [#A] Interfaces for calculating grades		  :grader:ui:
   - this probably needs to be done in tandem with system configuration
   - need way to map current course to a grading function:
     + naming convention?  e.g. calculate_grades_25A_fall2012?
       this is nice and simple but maybe not general enough...
       would get complicated when course numbers include characters that
       can't be in Python identifiers ('-', '.')
     + configuration must include a function that maps course rows to
       grading functions?
   - I've gone with the naming convention for now.  Let's see how it works.
** DONE [#A] Support for email in students table		      :db:ui:
** CANCELED [#B] Support for middle name in students table		 :db:
   I've decided the right thing to do here is to leave middle names
   in the first_name column, but implement proper fuzzy searching of
   the students table
** DONE [#B] More sophisticated searching			      :db:ui:
   currently all lookups are just exact matches, but this is going to
   become cumbersome for text fields (esp. names)
** DONE [#A] Interface to see/add/edit students in current course   :ui:edit:
** TODO [#A] Interface to see/edit grades in current assignment	    :ui:edit:
** TODO [#B] Interfaces to reporting functions		       :ui:reporting:
** TODO [#D] More sophisticated UI? Curses-based? 			 :ui:
** TODO [#C] Separation of 'view' and 'controller' UI code		 :ui:
** TODO [#B] Summary statistics					  :reporting:
 - for assignments
 - for a course overall
 - for a course in comparison to others
 - for individual students
 - measure improvement
** TODO [#C] PGP encryption/decryption of database file		      :ui:db:
** TODO [#A] Export grades to gradebook format		   :bspace:ui:export:
** DONE [#C] distribute on PyPI					  :packaging:
   - need to remove/abstract out Berkeley-specific code, like
     db.sid validator and bspace module
   - better keywords/metadata
   - docs
** TODO [#C] Interface for emailing grades, stats to students	  :ui:export:
** TODO [#C] Interface for creating mailing lists		  :ui:export:
** DONE [#A] System configuration			       :ui:packaging:
   Python module?  ConfigParser?
   - path to grader functions
   - path to db
   - current course(s) / semester, year
   - email setup

** TODO [#B] Support for readline					 :ui:
   - in db lookups 
   - in path 
** TODO [#B] DB-level sorting						 :db:
   - just have default ORDER BY clauses?
   - order_by interface in API?
** TODO [#B] Abstract get_student logic into incremental_search?	 :ui:
   - is it possible to have a generic interface for incremental seach
     that isn't too unwieldy?  so we could have get_student, get_course,
     get_assignment, ... which would all make for nicer interfaces
     for lookup-or-create type actions 
** DONE [#A] Make sure examples/*.py get installed in a reasonable place :packaging:bug:
   This is fixed reasonably well, for Debian-style systems at least;
   pip installs examples to /usr/local/share/schoolutils/examples.
   No idea if it works, or how, on Windows or other Unixes.  May need
   to revisit in the future.
** DONE [#A] Write docs for initial release!				:doc:
** TODO [#D] Make compatible with Python 3			  :packaging:
** DONE [#A] Figure out the best thing to do with user validators     :ui:db:
   useful validators include:
   - sid
   - course_num
   - assignment_name
   what's the proper behavior here?  should db module import user_validators,
   and wrap the appropriate validator in its own version?
   from schoolutils.config import user_validators
   def sid(s):
       if user_validators.sid:
          return user_validators.sid(s)
          # ...
** TODO [#A] Interfaces to edit existing assignments, courses, grades :ui:edit:
   - need to be able to modify and delete these
** DONE [#A] Make executable scripts with CLI options		     :ui:bin:
   - bin/grade: start the grader
     + -a "Paper 1" : select assignment
     + -c "course num" : select course
     + -e : enter grades
     + -g : calculate grades
     + -i : import students
     + -x : export grades
** TODO [#B] Interface for exporting (sorted) lists of grades	  :ui:export:
** TODO [#A] Test and fix nested KeyboardInterrupt loop breakout	 :ui:
** TODO [#B] Figure out institution setup				 :ui:
   - need an API definition for institution modules
     + validators?
     + csv formats?
   - institution var in user_config
   - import user_institution module in config? 
** TODO [#B] Improve change_database, change_course, change_assignment, etc. :ui:
   - edge case: should not have to retype db path if provided on CLI
     but no database exists there yet
   - implement current_courses option
   - incremental search for course, assignment?
   - calculate_all_grades interface to loop over all current courses
** TODO [#A] Fix grade calculation when grades for a given student are missing
* Bug notes
** f890cef9d: grading/ fix bug in select_students giving duplicate rows
   - problem was join: a student can appear in multiple courses, so
     if no course constraints are present, multiple student records can
     be returned
   - actually, there's still a problem in the case where course_name is
     given but the student is enrolled in multiple courses with the
     same name (or similar names with the _like version); but this edge
     case is rare enough that it probably won't happen for other
     reasons, so I won't fix it for now