Smug Enhancements

Author: Jeff Anderson

Something I've had on my todo list for a very long time now was to get my notes from School published automatically on my website. They are already stored in ReStructured Text, and they are already stored in git repositories, so my use of smug already had me 95% of the way there. (I have a write-up about my note taking method: here)

I spent my day off, and finally found some better approaches to the problems I had, and I now have automatic sharing of my notes on my website.

The thing that was holding me back was the fact that smug couldn't do everything I wanted it to. I also store other things, such as homework, papers, and other assignments in the same git repository. Also, the way that I would organize a website is different than I would organize my personal files.

Here is an example of how I might have a git repository laid out for a given class:


This is a very logical way to lay out my own personal repository. If I decide to work on this class, I simply change to the base directory, and I can easily access all three subdirectories.

On a website, I'm only interested in sharing my notes. Since I have lots of classes, and they all have notes, I might want to do one of the following layouts for just my notes:


The content is already contained in a git repo, but smug would only graft the entire repo onto my web path. Smug doesn't yet have access controls, so my options were limited to something like mod_rewrite.

For a long time, I thought that access control would be the best way to address the problem, and then it just hit me. The answer is a simple change to smug that allows me to graft my repository, along with a prefix, to my web location.

It didn't take long for me to get a working patch. The only change I made was the ability to add a prefix keyword argument to the smug url context. I can now have a repository that has lots of classes complete with notes, homework, study material, research papers, source code, and anything else that I would like to keep private.

I can even include smug.urls in my url configuration multiple times with several paths. I used to keep all classes in one large git repository, so I have a "school" repository defined in my SMUG_REPOSITORIES, and several inclusions of smug.urls with different prefixes on the same repository:

urlpatterns += patterns('',
    (r'^school/notes/rel212/', include('smug.urls'), {'repo': 'school',
    'prefix': 'rel212/notes/'}),
    (r'^school/notes/math113/', include('smug.urls'), {'repo': 'school',
    'prefix': 'math113/notes/'}),
    (r'^school/notes/ecen924/', include('smug.urls'), {'repo': 'school',
    'prefix': 'ecen924/notes/'}),

Take a look at for a list of the classes I currently have posted.

The other hurdle that I had to jump was the fact that I make extensive use of latex-style equations in my notes. I have a Makefile that can in fact generate valid xhtml with MathML rendered equations. I very much liked the output of MathML equations.

The problem with MathML is mostly compatibility, and the difficulty of being sure that smug would output valid xhtml. It doesn't always work using my Makefile.

Also, my Makefile depends on several stages of processing. First the html4 source is generated by docutils, followed by the running of sed to change dollar signs to brackets. The dollar signs are required for the latex output to function correctly, but the processor that converts the equations to MathML needed brackets. Next, the processor itself was run itex2MML. This converts the equations well enough, but it doesn't support everything that LaTeX supports, but it doesn't support everything that MathML supports either. The most notable exception is \overrightarrow and other similar commands. After itex2MML is done, a special MathML-aware version of tidy must be run. This special version comes with itex2MML. In the end, all the docutils css formatting was lost, but the document had outstanding equations.

I decided to give jsMath a look. I just dropped in the jsMath script tag onto my website, and any rst documents that have raw LaTeX equations worked fine. jsMath is now my friend. No more hassle.

So, with the addition of my prefix patch to smug, and my discovery of jsMath, all I needed to do was add my repositories to my urls, and sit back. I ended up tweaking some of the CSS that I wrote for ReST, which still isn't complete. I've also noticed that jsMath doesn't recognize all of my equation markup.

I wrote a handful of other small improvements to smug's rst filters. It now honors the Django RESTRUCTUREDTEXT_FILTER_SETTINGS that is used for django.contrib.markup.

Posted: Jun 13, 2009 | Tags: Django Open Source git Smug Python School Servers
  • brisbane said at Jun 14, 2009:

    Wonderful Job! Thanks for sharing.

Comments are closed.