README

   1 ``pygrader`` is a directory-based grade database for grading course
   2 assignments.  Besides tracking grades locally, you can also use it to
   3 automatically mail grades to students and professors associated with
   4 the course.  For secure communication, PGP_ can be used to sign and/or
   5 encrypt any of these emails.
   6
   7 Installation
   8 ============
   9
  10 Packages
  11 --------
  12
  13 Gentoo
  14 ~~~~~~
  15
  16 I've packaged ``pygrader`` for Gentoo_.  You need layman_ and
  17 my `wtk overlay`_.  Install with::
  18
  19   # emerge -av app-portage/layman
  20   # layman --add wtk
  21   # emerge -av dev-python/pygrader
  22
  23 Dependencies
  24 ------------
  25
  26 ``pygrader`` is a simple package.  The only external dependency
  27 outside the Python 3 standard library is my `pgp-mime`_ package.
  28
  29 If you are developing ``pygrader``, you can use `update-copyright`_ to
  30 keep the copyright blurbs up to date.
  31
  32 Installing by hand
  33 ------------------
  34
  35 ``pygrader`` is available as a Git_ repository::
  36
  37   $ git clone git://tremily.us/pygrader.git
  38
  39 See the homepage_ for details.  To install the checkout, run the
  40 standard::
  41
  42   $ python setup.py install
  43
  44 Usage
  45 =====
  46
  47 Pygrader will help keep you organized in a course where the students
  48 submit homework via email, or the homework submissions are otherwise
  49 digital (i.e. scanned in after submission).  There is currently no
  50 support for multiple graders, although I will likely add this in the
  51 future.  In the following sections, I'll walk you through
  52 administering the homework for the ``test`` course.
  53
  54 All of the processing involves using the ``pg.py`` command.  Run::
  55
  56   $ pg.py --help
  57
  58 for details.
  59
  60 Sending email
  61 -------------
  62
  63 Pygrader receives submissions and assigns grades via email.  In order
  64 to send email, it needs to connect to an SMTP_ server.  See the
  65 pgp-mime documentation for details on configuring you SMTP connection.
  66 You can test your SMTP configuration by sending yourself a test
  67 message::
  68
  69   $ pg.py -VVV smtp -a rincewind@uu.edu -t rincewind@uu.edu
  70
  71 Defining the course
  72 -------------------
  73
  74 Once you've got email submission working, you need to configure the
  75 course you'll be grading.  Each course lives in its own directory, and
  76 the basic setup looks like the ``test`` example distributed with
  77 pygrader.  The file that you need to get started is the config file in
  78 the course directory::
  79
  80   $ cat test/course.conf
  81   [course]
  82   name: Physics 101
  83   assignments: Attendance 1, Attendance 2, Attendance 3, Attendance 4,
  84     Attendance 5, Attendance 6, Attendance 7, Attendance 8, Attendance 9,
  85     Assignment 1, Assignment 2, Exam 1, Exam 2
  86   robot: Robot101
  87   professors: Gandalf
  88   assistants: Sauron
  89   students: Bilbo Baggins, Frodo Baggins, Aragorn
  90
  91   [Attendance 1]
  92   points: 1
  93   weight: 0.1/9
  94   due: 2011-10-03
  95
  96   [Attendance 2]
  97   points: 1
  98   weight: 0.1/9
  99   due: 2011-10-04
 100
 101   …
 102
 103   [Assignment 1]
 104   points: 10
 105   weight: 0.4/2
 106   due: 2011-10-10
 107   submittable: yes
 108
 109   …
 110
 111   [Exam 2]
 112   points: 10
 113   weight: 0.4/2
 114   due: 2011-10-17
 115
 116   [Robot101]
 117   nickname: phys-101 robot
 118   emails: phys101@tower.edu
 119   pgp-key: 4332B6E3
 120
 121   [Gandalf]
 122   nickname: G-Man
 123   emails: g@grey.edu
 124   pgp-key: 4332B6E3
 125
 126   [Sauron]
 127   emails: eye@tower.edu
 128
 129   [Bilbo Baggins]
 130   nickname: Bill
 131   emails: bb@shire.org, bb@greyhavens.net
 132
 133   …
 134
 135 The format is a bit wordy, but it is also explicit and easily
 136 extensible.  The time it takes to construct this configuration file
 137 should be a small portion of the time you will spend grading
 138 submissions.
 139
 140 If a person has the ``pgp-key`` option set, that key will be used to
 141 encrypt messages to that person and sign messages from that person
 142 with PGP_.  It will also be used to authenticate ownership of incoming
 143 emails.  You'll need to have GnuPG_ on your local host for this to
 144 work, and the user running pygrader should have the associated keys in
 145 their keychain.
 146
 147 The ``course.robot`` option defines a dummy person used to sign
 148 automatically generated emails (e.g. responses to mailpipe-processed
 149 submissions).
 150
 151 The ``submittable`` option marks assignments that accept direct
 152 submission from students (e.g. homeworks).  You probably don't want to
 153 set this option for attendance, since it would allow students to mark
 154 themselves as having attended a class.  ``submittable`` default to
 155 ``False``.
 156
 157 Processing submissions
 158 ----------------------
 159
 160 As the due date approaches, student submissions will start arriving in
 161 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into
 162 directories.  This will also extract any files that were attached to
 163 the emails and place them in that persons assignment directory::
 164
 165   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 166
 167 Use ``pg.py``'s ``todo`` command to check for ungraded submissions::
 168
 169   $ pg.py -d test todo mail grade
 170
 171 To see how everyone's doing, you can print a table of grades with
 172 ``pg.py``'s ``tabulate`` command::
 173
 174   $ pg.py -d test tabulate -s
 175
 176 When you want to notify students of their grades, you can send them
 177 all out with ``pg.py``'s ``email`` command::
 178
 179   $ pg.py -d test email assignment 'Exam 1'
 180
 181 Testing
 182 =======
 183
 184 Run the internal unit tests using nose_::
 185
 186   $ nosetests --with-doctest --doctest-tests pygrader
 187
 188 If a Python-3-version of ``nosetests`` is not the default on your
 189 system, you may need to try something like::
 190
 191   $ nosetests-3.2 --with-doctest --doctest-tests pygrader
 192
 193 Licence
 194 =======
 195
 196 This project is distributed under the `GNU General Public License
 197 Version 3`_ or greater.
 198
 199 Author
 200 ======
 201
 202 W. Trevor King
 203 wking@tremily.us
 204
 205 Related work
 206 ============
 207
 208 For a similar project, see `Alex Heitzmann's pygrade`_, which keeps
 209 the grade history in a single log file and provides more support for
 210 using graphical interfaces.
 211
 212
 213 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 214 .. _Gentoo: http://www.gentoo.org/
 215 .. _layman: http://layman.sourceforge.net/
 216 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 217 .. _pgp-mime: http://blog.tremily.us/posts/pgp-mime/
 218 .. _update-copyright: http://blog.tremily.us/posts/update-copyright/
 219 .. _Git: http://git-scm.com/
 220 .. _homepage: http://blog.tremily.us/posts/pygrader/
 221 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 222 .. _GnuPG: http://www.gnupg.org/
 223 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 224 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 225 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/