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   robot: Robot101
  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   professors: Gandalf
  87   assistants: Sauron
  88   students: Bilbo Baggins, Frodo Baggins, Aragorn
  89
  90   [Attendance 1]
  91   points: 1
  92   weight: 0.1/9
  93   due: 2011-10-03
  94
  95   [Attendance 2]
  96   points: 1
  97   weight: 0.1/9
  98   due: 2011-10-04
  99
 100   …
 101
 102   [Assignment 1]
 103   points: 10
 104   weight: 0.4/2
 105   due: 2011-10-10
 106   submittable: yes
 107
 108   …
 109
 110   [Exam 2]
 111   points: 10
 112   weight: 0.4/2
 113   due: 2011-10-17
 114
 115   [Robot101]
 116   nickname: phys101 robot
 117   emails: phys101@tower.edu
 118   pgp-key: 4332B6E3
 119
 120   [Gandalf]
 121   nickname: G-Man
 122   emails: g@grey.edu
 123   pgp-key: 4332B6E3
 124
 125   [Sauron]
 126   emails: eye@tower.edu
 127
 128   [Bilbo Baggins]
 129   nickname: Bill
 130   emails: bb@shire.org, bb@greyhavens.net
 131
 132   …
 133
 134 The format is a bit wordy, but it is also explicit and easily
 135 extensible.  The time it takes to construct this configuration file
 136 should be a small portion of the time you will spend grading
 137 submissions.
 138
 139 If a person has the ``pgp-key`` option set, that key will be used to
 140 encrypt messages to that person and sign messages from that person
 141 with PGP_.  It will also be used to authenticate ownership of incoming
 142 emails.  You'll need to have GnuPG_ on your local host for this to
 143 work, and the user running pygrader should have the associated keys in
 144 their keychain.
 145
 146 The ``course.robot`` option defines a dummy person used to sign
 147 automatically generated emails (e.g. responses to mailpipe-processed
 148 submissions).
 149
 150 The ``submittable`` option marks assignments that accept direct
 151 submission from students (e.g. homeworks).  You probably don't want to
 152 set this option for attendance, since it would allow students to mark
 153 themselves as having attended a class.  ``submittable`` default to
 154 ``False``.
 155
 156 Processing submissions
 157 ----------------------
 158
 159 As the due date approaches, student submissions will start arriving in
 160 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into
 161 directories.  This will also extract any files that were attached to
 162 the emails and place them in that persons assignment directory::
 163
 164   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 165
 166 Use ``pg.py``'s ``todo`` command to check for ungraded submissions::
 167
 168   $ pg.py -d test todo mail grade
 169
 170 To see how everyone's doing, you can print a table of grades with
 171 ``pg.py``'s ``tabulate`` command::
 172
 173   $ pg.py -d test tabulate -s
 174
 175 When you want to notify students of their grades, you can send them
 176 all out with ``pg.py``'s ``email`` command::
 177
 178   $ pg.py -d test email assignment 'Exam 1'
 179
 180 Testing
 181 =======
 182
 183 Run the internal unit tests using nose_::
 184
 185   $ nosetests --with-doctest --doctest-tests pygrader
 186
 187 If a Python-3-version of ``nosetests`` is not the default on your
 188 system, you may need to try something like::
 189
 190   $ nosetests-3.2 --with-doctest --doctest-tests pygrader
 191
 192 Licence
 193 =======
 194
 195 This project is distributed under the `GNU General Public License
 196 Version 3`_ or greater.
 197
 198 Author
 199 ======
 200
 201 W. Trevor King
 202 wking@tremily.us
 203
 204 Related work
 205 ============
 206
 207 For a similar project, see `Alex Heitzmann's pygrade`_, which keeps
 208 the grade history in a single log file and provides more support for
 209 using graphical interfaces.
 210
 211
 212 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 213 .. _Gentoo: http://www.gentoo.org/
 214 .. _layman: http://layman.sourceforge.net/
 215 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 216 .. _pgp-mime: http://blog.tremily.us/posts/pgp-mime/
 217 .. _update-copyright: http://blog.tremily.us/posts/update-copyright/
 218 .. _Git: http://git-scm.com/
 219 .. _homepage: http://blog.tremily.us/posts/pygrader/
 220 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 221 .. _GnuPG: http://www.gnupg.org/
 222 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 223 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 224 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/