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