Python Paste


Commentary

Introduction

Commentary is a commenting system written by Ian Bicking.

It is initially intended to facilitate feedback on project documentation, allowing anonymous submitters to add notes to documentation.

Features

  • Double-click anywhere to comment.
  • Comments are stored in simple text files.
  • Comments for each file/URI are stored together in a single file.
  • Edits to those files are reflected on the website (you do not have to use the web interface to manage the comments).
  • Files are automatically committed to Subversion, if the comments are stored in a Subverion checkout.
  • Comment locations are specified the id of an element and an offset. These are moderately resistent to getting lost as the document changes (though drifting is certainly possible). This is especially true for HTML generated with lots of ids; even better when the ids are meaningful (as in restructured text).
  • Implemented as WSGI middleware, so it can be wrapped around any WSGI application. With an HTTP proxy WSGI application it could be wrapped around any website.
  • Uses Javascript on the client side to make for a more pleasant experience.

Configuration

A simple configuration will look like this:

[filter-app:main]
use = egg:Commentary
storage = /path/to/checkout/$path_info_dir/$path_info_base.comments.txt
body_start_re = ...
body_end_re = ...
input_encoding = ISO-8859-1
next = docs

[app:docs]
use = egg:Paste#static
document_root = /path/to/html

The first section says there is an application named "main" that wraps an application named "docs"; and the docs application is just an app that serves static files.

body_start_re and body_end_re are regular expressions that match the "real" start and end of the body. I.e., you can use these to identify where the navigation ends, and where commentable content begins.

storage is where the files get stored to. Well, it's actually a pattern, with the variables:

$path_info_file:
The filename (no directory)
$path_info_dir:
The URI directory (no filename)
$path_info:
The full path (URI directory + filename)
$path_info_base:
The filename (no directory) without extension
$path_info_ext:
The extension

You can use this to, for instance, put all comments in subdirectories of the file they are commenting on. Also, it's just the URI directory (and the URI under where Commentary itself is installed), so you usually give a prefix as well. E.g., if you are commenting on http://host/lib/libname.html, then $path_info_dir will be /lib.

If the location is a Subversion checkout, Commentary will commit all the changes submitted through the website. It always creates directories as necessary.

Once you have this configuration, you have something ready for use with Paste Deploy.

For a quick start, also add this section:

[server:main]
use = egg:PasteScript#wsgiutils
port = 8080
# Change to 0.0.0.0 to make public:
host = 127.0.0.1

And install Paste Script and run paster serve config:config_file.ini and you'll get the application served up on http://localhost:8080.