What does this application do?
The value of a document published to the web can benefit tremendously from interaction with its readers. Their help with correcting typos, improving clarity, or enhancing the document with their experiences and notes is helpful for other readers, and the original author(s).
ucomment is a Django application that allows for web-based commenting on a document. Unlike other commenting systems, ucomment was developed specifically for commenting on evolving documentation. In other words, the comments are to be integrated (directly, or modified), into the document by the author, and then the revised document can be published again to the web. Comments can easily be moved to other locations in the document, or simply removed by the author.
ucomment will work also with documents that are static.
ucomment requires the author write the document using reStructuredText in one or more text files.
The Sphinx documentation generator is used to convert the reStructuredText to HTML output. This allows other powerful Sphinx enhancements to be used. Sphinx can also be used to generate PDF, ebook, and other output formats from your document.
A distributed version control system is used to track all revisions and comments added to the document. Currently only Mercurial is supported, others can easily be added.
Finally, Django is used to store all comments, page visits, user statistics, implement server-side search for the document, and comment administration, using the Django admin interface.
Once the document is published to the web, visitors may comment on the document. Comments must be approved by a site administrator (customizable), via a single-click URL to either accept or reject the comment. Once approved, comments will appear on the site with the next page refresh.
The Sphinx documentation generator already provides good-looking tabular output, mathematical equations, and so forth. But if you need further enhancements, simply adjust the templates and cascading style sheets elements that come with ucomment.
An example of ucomment in action is this website. The source code for this document is available here.
Other web-based commenting systems
Full credit for the idea of web-based commenting goes to various websites, particularly The Django Book which was the strongest source of ideas for ucomment. That site shows comments in a sidebar, with speech bubbles either containing a number (if there are existing comments) or no number. These bubbles invite the user to click on them to view the existing comments, or add their own comment.
The site for the book called Mercurial: The Definitive Guide follows a similar idea, but uses inline commenting. A link appears after every paragraph, figure, source code snippet, etc, that either shows “No comments” or “N comments”, where N is some integer.
ucomment implements the type of comments as used on the Django Book website. Inline commenting could be added to ucomment, but is not currently implemented. (I personally find inline commenting a bit distracting.)
Bullet point feature summary
Visitors to the document website can turn comments on or off (sometimes its nice to just read the document, without extra visual distraction!).
The document can be updated and republished on the web, and the original comments will correctly move to the updated location.
Links for Next, Previous and Table of Contents help the reader navigate the various sections of the document.
Comments are written in reStructuredText (allows for math, bullet points, tables, etc), and must be previewed by the reader before being submitted.
Once submitted, the comment administrator can approve or rejects new comments via email links; the comment submitter is informed of the decision by email also.
Email alerts are sent to the site administrator if any errors occurs.
The settings for comment acceptance are flexible. For example, the default settings will auto-approve future comments from a poster who has submitted 3 or more approved comments in the past.
Any comments can always be removed from the document’s web output by marking a checkbox in the Django admin site, or by deleting the comment from the Django database.
When the user navigates back to the table of contents they are shown the page they came from; to help navigate large documents.
Support for mathematics and comments on equations: MathJax and pngmath (a Sphinx extension) have been tested.
Simple, full text search of the document is available; a feature request is that other 3rd party search plugins can be used instead.
Search is accessible via a URL:
will perform a case-insensitive search for the word search and Term. The AND can be replaced with OR.
A customizable template is provided so that you can render the page within your existing website and surround the document content with other content. Templated items include:
The main content area
Sidebar containing the search box and the local ToC
Page navigation elements
Emails sent to users and the site administrators
Basic tracking of page hits (visits) and page popularity can be followed in the Django admin interface. (see code in the application’s admin.py file to modify the admin interface).
A server setting exists to stop all commenting on the document, and to not display any existing comments.
Experimental: long chapters or sections in the document can be optionally split into smaller subsections that each appear on their own HTML page.
For now, if you wish to split up a long document you must write the section in separate RST files. The experimental features allows you to edit inside single RST files, but then automatically splits them up.