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.
 131
 132 Processing submissions
 133 ----------------------
 134
 135 As the due date approaches, student submissions will start arriving in
 136 your inbox.  Use ``pg.py``'s ``mailpipe`` command to sort them into
 137 directories.  This will also extract any files that were attached to
 138 the emails and place them in that persons assignment directory::
 139
 140   $ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
 141
 142 Use ``pg.py``'s ``todo`` command to check for ungraded submissions::
 143
 144   $ pg.py -d test todo mail grade
 145
 146 To see how everyone's doing, you can print a table of grades with
 147 ``pg.py``'s ``tabulate`` command::
 148
 149   $ pg.py -d test tabulate -s
 150
 151 When you want to notify students of their grades, you can send them
 152 all out with ``pg.py``'s ``email`` command::
 153
 154   $ pg.py -d test email assignment 'Exam 1'
 155
 156 Testing
 157 =======
 158
 159 Run the internal unit tests using nose_::
 160
 161   $ nosetests --with-doctest --doctest-tests pygrader
 162
 163 If a Python-3-version of ``nosetests`` is not the default on your
 164 system, you may need to try something like::
 165
 166   $ nosetests-3.2 --with-doctest --doctest-tests pygrader
 167
 168 Licence
 169 =======
 170
 171 This project is distributed under the `GNU General Public License
 172 Version 3`_ or greater.
 173
 174 Author
 175 ======
 176
 177 W. Trevor King
 178 wking@drexel.edu
 179
 180 Related work
 181 ============
 182
 183 For a similar project, see `Alex Heitzmann's pygrade`_, which keeps
 184 the grade history in a single log file and provides more support for
 185 using graphical interfaces.
 186
 187
 188 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 189 .. _Gentoo: http://www.gentoo.org/
 190 .. _layman: http://layman.sourceforge.net/
 191 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 192 .. _pgp-mime: http://blog.tremily.us/posts/pgp-mime/
 193 .. _update-copyright: http://blog.tremily.us/posts/update-copyright/
 194 .. _Git: http://git-scm.com/
 195 .. _homepage: http://blog.tremily.us/posts/pygrader/
 196 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 197 .. _GnuPG: http://www.gnupg.org/
 198 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 199 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
 200 .. _Alex Heitzmann's pygrade: http://code.google.com/p/pygrade/