storage: cleanup StubCourse after load_course doctest.

[pygrader.git] / README

diff --git a/README b/README
index 2b5e863022384dd0f6fe5063f3e70860a2af15e5..f0318d4159e248898cfbbd9acc1dd801ecd74998 100644 (file)
--- a/README
+++ b/README
@@ -79,9 +79,11 @@ the course directory::
 
   $ cat test/course.conf
   [course]
 
   $ cat test/course.conf
   [course]

+  name: Physics 101

   assignments: Attendance 1, Attendance 2, Attendance 3, Attendance 4,
     Attendance 5, Attendance 6, Attendance 7, Attendance 8, Attendance 9,
     Assignment 1, Assignment 2, Exam 1, Exam 2
   assignments: Attendance 1, Attendance 2, Attendance 3, Attendance 4,
     Attendance 5, Attendance 6, Attendance 7, Attendance 8, Attendance 9,
     Assignment 1, Assignment 2, Exam 1, Exam 2

+  robot: Robot101

   professors: Gandalf
   assistants: Sauron
   students: Bilbo Baggins, Frodo Baggins, Aragorn
   professors: Gandalf
   assistants: Sauron
   students: Bilbo Baggins, Frodo Baggins, Aragorn


@@ -98,11 +100,24 @@ the course directory::
 
   …
 
 
   …
 

+  [Assignment 1]
+  points: 10
+  weight: 0.4/2
+  due: 2011-10-10
+  submittable: yes
+
+  …
+

   [Exam 2]
   points: 10
   weight: 0.4/2
   due: 2011-10-17
 
   [Exam 2]
   points: 10
   weight: 0.4/2
   due: 2011-10-17
 

+  [Robot101]
+  nickname: phys-101 robot
+  emails: phys101@tower.edu
+  pgp-key: 4332B6E3
+

   [Gandalf]
   nickname: G-Man
   emails: g@grey.edu
   [Gandalf]
   nickname: G-Man
   emails: g@grey.edu


@@ -129,13 +144,24 @@ emails.  You'll need to have GnuPG_ on your local host for this to
 work, and the user running pygrader should have the associated keys in
 their keychain.
 
 work, and the user running pygrader should have the associated keys in
 their keychain.
 

+The ``course.robot`` option defines a dummy person used to sign
+automatically generated emails (e.g. responses to mailpipe-processed
+submissions).
+
+The ``submittable`` option marks assignments that accept direct
+submission from students (e.g. homeworks).  You probably don't want to
+set this option for attendance, since it would allow students to mark
+themselves as having attended a class.  ``submittable`` default to
+``False``.
+

 Processing submissions
 ----------------------
 
 As the due date approaches, student submissions will start arriving in
 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into
 Processing submissions
 ----------------------
 
 As the due date approaches, student submissions will start arriving in
 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into

-directories.  This will also extract any files that were attached to
-the emails and place them in that persons assignment directory::
+directories (using the ``pygrader.handler.submission`` handler).  This
+will also extract any files that were attached to the emails and place
+them in that persons assignment directory::

 
   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 
 
   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 


@@ -143,6 +169,16 @@ Use ``pg.py``'s ``todo`` command to check for ungraded submissions::
 
   $ pg.py -d test todo mail grade
 
 
   $ pg.py -d test todo mail grade
 

+Then create ``grade`` files using your favorite editor.  The first
+line of the grade file should be the student's grade for that
+assigment, expressed in a syntax that Python's ``float()`` understands
+(``1``, ``95``, ``2.5``, ``6.022e23``, etc.).  If you wish, you may
+add additional comment lines after the grade line, offering
+suggestions for improvement, etc.  This comment (if present) will be
+mailed to the student along with the grade itself.  There are a number
+of example grade files in the ``test`` directory in ``pygrader``'s Git
+source.
+

 To see how everyone's doing, you can print a table of grades with
 ``pg.py``'s ``tabulate`` command::
 
 To see how everyone's doing, you can print a table of grades with
 ``pg.py``'s ``tabulate`` command::
 


@@ -153,6 +189,63 @@ all out with ``pg.py``'s ``email`` command::
 
   $ pg.py -d test email assignment 'Exam 1'
 
 
   $ pg.py -d test email assignment 'Exam 1'
 

+Mailpipe details
+~~~~~~~~~~~~~~~~
+
+Mailpipe is the most complicated part of ``pygrader``, and the place
+where things are most likely to get sticky.  Since there are several
+
+If you get tired of filtering your inbox by hand using ``pg.py
+mailpipe``, you can (depending on how your mail delivery is setup) use
+procmail_ to automatically run ``mailpipe`` automatically on incoming
+email.  There is an example ``.procmailrc`` in the
+``pygrader.mailpipe.mailpipe`` docstring that runs ``mailpipe``
+whenever incoming emails have ``[phys160:submit]`` in their subject
+somewhere.
+
+The use of ``[TARGET]`` tags in the email subject allows users to
+unambiguously specify the purpose of their email.  Currently supported
+targets include (see the ``handlers`` argument to
+``pygrader.mailpipe``):
+
+``submit``
+  student assignment submission.  The remainder of the email subject
+  should include the case insensitive name of the assignment being
+  submitted (see ``pygrader.handler.submission._match_assignment``).
+  An example subject would be::
+
+    [submit] assignment 1
+
+``get``
+  request information from the grade database.  For students, the
+  remainder of the email subject is irrelevant.  Grades and comments
+  for all graded assignments are returned in a single email.  An
+  example subject would be::
+
+    [get] my grades
+
+  Professors and TAs may request either a table of all grades for the
+  course (à la ``tabulate``), the full grades for a particular
+  student, or a particular student's submission for a particular
+  assignment.  Example subjects are (respectively):
+
+    [get] don't match any student names
+    [get] Bilbo Baggins
+    [get] Bilbo Baggins Assignment 1
+
+To allow you to easily sort the email, you can also prefix the target
+with additional information (see
+``pygrader.mailpipe._get_message_target``).  For example, if you were
+running several courses from the same email account, you'd want a way
+for users to specify which course they were interacting with so you
+could filter appropriately in your procmail rules.  Everything in the
+subject tag before an optional semicolon is ignored by ``mailpipe``,
+so the following subjects will be handled identically::
+
+  [submit] assignment 1
+  [phys101:submit] assignment 1
+  [phys101:section2:submit] assignment 1
+

 Testing
 =======
 
 Testing
 =======
 


@@ -175,7 +268,7 @@ Author
 ======
 
 W. Trevor King
 ======
 
 W. Trevor King

-wking@drexel.edu
+wking@tremily.us

 
 Related work
 ============
 
 Related work
 ============


@@ -195,6 +288,7 @@ using graphical interfaces.
 .. _homepage: http://blog.tremily.us/posts/pygrader/
 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 .. _GnuPG: http://www.gnupg.org/
 .. _homepage: http://blog.tremily.us/posts/pygrader/
 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 .. _GnuPG: http://www.gnupg.org/

+.. _procmail: http://www.procmail.org/

 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/
 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/