Dependencies
------------
-``pygrader`` is a simple package. The only external dependency
-outside the Python 3 standard library is my `pgp-mime`_ package.
+If you're installing by hand or packaging pycomedi for another
+distribution, you'll need the following dependencies:
+
+======== ===================== ================ =========================
+Package Purpose Debian_ Gentoo_
+======== ===================== ================ =========================
+Jinja_ email templating python-jinja2 dev-python/jinja
+pgp-mime_ secure email dev-python/pgp-mime [#pm]
+nose_ testing (optional) python-nose dev-python/nose
+NumPy_ statistics (optional) python-numpy dev-python/numpy
+========= ===================== ================ =========================
+
+If NumPy is not installed, we'll fall back to internal implementations
+of the various statistical calculations.
If you are developing ``pygrader``, you can use `update-copyright`_ to
keep the copyright blurbs up to date.
+.. [#pm] In the `wtk overlay`_.
+
Installing by hand
------------------
Pygrader will help keep you organized in a course where the students
submit homework via email, or the homework submissions are otherwise
-digital (i.e. scanned in after submission). There is currently no
-support for multiple graders, although I will likely add this in the
-future. In the following sections, I'll walk you through
-administering the homework for the ``test`` course.
+digital (i.e. scanned in after submission). You can also use it to
+assign and `manage any type of grade via email`__. In the following
+sections, I'll walk you through local administration for the ``test``
+course.
+
+__ `Mailpipe details`_
All of the processing involves using the ``pg.py`` command. Run::
encrypt messages to that person and sign messages from that person
with PGP_. It will also be used to authenticate ownership of incoming
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
your inbox. Use ``pg.py``'s ``mailpipe`` command to sort them into
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::
+them in that person's assignment directory::
$ pg.py -d test mailpipe -m maildir -i ~/.maildir -o ./mail-old
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
+Besides accepting student submissions from incoming email,
+``mailpipe`` also accepts other types of requests, and can be
+configured to respond automatically:
+
+* Incoming student assignment submissions are archived (see the
+ ``submit`` command).
+* Students can check their grades without having to bother anyone (see
+ the ``get`` commands).
+* Professors and teaching assistants can request student submissions
+ so that they can grade them (see the ``get`` commands).
+* Professors and TAs can request the grades for the entire class (see
+ the ``get`` commands).
+* Professors and TAs can assign grades (see the ``grade`` command).
+
+To enable automatic responses, you'll need to add the ``-r`` or
+``--respond`` argument when you call ``pg.py``.
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
[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
+
+``grade``
+ professors and TAs can submit a grade for a particular student on a
+ particular assignment. The body of the (possibly signed or
+ encrypted) email should be identical to the grade file that the
+ sender wishes to create. An example subject would be::
+
+ [grade] 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
.. _Gentoo: http://www.gentoo.org/
.. _layman: http://layman.sourceforge.net/
.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
+.. _Debian: http://www.debian.org/
+.. _Gentoo: http://www.gentoo.org/
+.. _Jinja: http://jinja.pocoo.org/
.. _pgp-mime: http://blog.tremily.us/posts/pgp-mime/
+.. _NumPy: http://numpy.scipy.org/
.. _update-copyright: http://blog.tremily.us/posts/update-copyright/
.. _Git: http://git-scm.com/
.. _homepage: http://blog.tremily.us/posts/pygrader/
projects / pygrader.git / blobdiff