Richard Lawrence committed 5f6a834 Merge

Merge branch 'grader_features'

Comments (0)

Files changed (5)

+v0.1.2, 2013-01-15 -- Add 'grade' script, README documentation 
 v0.1.1, 2013-01-14 -- Fix installation of examples/ and add classifiers
 v0.1.0, 2013-01-14 -- Initial relase.
 * tools for reporting grade statistics
 * tools for receiving student assignments via email, and returning
   graded assignments and comments via email
+The easiest way to install schoolutils is via `pip
+  $ pip install schoolutils
+You can also `download
+<>`_ the package from
+PyPI, unpack it, and run::
+  $ python install
+from the package directory.
+Finally, you can get the development version with ``git``::
+  $ git clone
+schoolutils has no dependencies (besides the Python standard library),
+so the installation should go smoothly; if you have any problems, please
+`report a bug <>`_.
+It isn't necessary to configure schoolutils, but it will be faster to
+use if you do.  The command-line UI expects to find configuration
+files in the ``.schoolutils`` directory of your home directory.  You
+should create two Python modules there: ```` and
+````.  Sample configuration files are included in the
+``examples`` directory of the source package::
+  $ mkdir ~/.schoolutils
+  $ cp path/to/schoolutils_source/examples/*.py ~/.schoolutils
+The comments in the sample files explain the values you should provide
+there.  The most important one in ```` is ``gradedb_file``,
+which should contain the path to your grade database file.  If you
+don't provide this value, you will have to type it in every time you
+start the grading program.
+First run
+Once you've installed the package, you can run the grading program as
+  $ grade
+This will start the grading program's interactive user interface with
+the configuration you specified in your ```` module.
+From there, you can:
+1) Add a course
+2) Add or import students into the course
+3) Add assignments
+4) Start entering grades
+After that
+A few concepts
+The grading program has a few important concepts you should be aware
+Currently selected course and assignment
+  The grading program has a notion of the 'current course' and
+  'current assignment'.  Most of the actions you take in the grading
+  program depend on your having previously selected a course or
+  assignment.  For example, when you add or import students, the
+  grading program will add them as members of the current course.
+  When you enter grades, you will be entering grades for the current
+  assignment.  You can specify the current course and assignment in
+  your ```` module, or select them interactively. 
+Entered vs. calculated grades
+  'Entered' grades are grades you have entered into the database
+  through the interactive interface.  These are the sort of grades you
+  produce by hand: for example, letter grades for a batch of papers
+  that you've graded.
+  'Calculated' grades are grades you use the grading program to
+  calculate.  Grades are calculated by a Python function that you must
+  provide, in your ```` module (see below).  These will
+  also be saved in the database, when you run the grade calculation
+  command.
+  You can use the grading program without ever calculating grades, but
+  it will (hopefully!) save you some work if you do.
+Grade calculation function
+  A grade calculation function is a function you define, in your
+  ```` module.  This function should calculate the
+  calculated grades for a single student on the basis of entered
+  grades.  You should define one grade calculation function per
+  course.
+  Grade calculation functions use a special naming convention so the
+  grading program knows which function to use when calculating
+  grades.  The name should be::
+    calculate_grade_<course number>_<semester><year>
+  For example, if you are teaching a course numbered '12A' in the fall
+  semester of 2013, you'd write a grade calculation function named::
+    calculate_grade_12A_fall2013
+  Each grade calculation function will receive a dictionary as input,
+  representing a single student's (entered) grades in the current
+  course.  The keys of the input dictionary are assignment names; the
+  values are grade values.  The function should return a dictionary
+  with the same keys and values for the entered grades, as well as a
+  new key and value for each calculated grade.  For more information,
+  see the example ```` module.
+Command-line options
+To see command-line options available for the grading program, use::
+  $ grade --help
+#!/usr/bin/env python
+from schoolutils.grading import ui
+if __name__ == '__main__':
+  u = ui.SimpleUI()
+  u.main_loop()
+  exit(0)
      that isn't too unwieldy?  so we could have get_student, get_course,
      get_assignment, ... which would all make for nicer interfaces
      for lookup-or-create type actions 
-** TODO [#A] Make sure examples/*.py get installed in a reasonable place :packaging:bug:
+** DONE [#A] Make sure examples/*.py get installed in a reasonable place :packaging:bug:
+   This is fixed reasonably well, for Debian-style systems at least;
+   pip installs examples to /usr/local/share/schoolutils/examples.
+   No idea if it works, or how, on Windows or other Unixes.  May need
+   to revisit in the future.
 ** TODO [#A] Write docs for initial release!				:doc:
 ** TODO [#D] Make compatible with Python 3			  :packaging:
 ** TODO [#A] Figure out the best thing to do with user validators     :ui:db:
 from distutils.core import setup
-      version='0.1.1',
+      version='0.1.2',
       description=('Utilities to track and manage student data, including '
                    'a grade database, grade calculators, and more'),
+        'schoolutils.institutions.ucberkeley',
+      scripts=['bin/grade',],
       data_files=[('share/schoolutils/examples', ['examples/',
-      #scripts=['bin/grade',],