Hieroglyph 0.5.5

As I mentioned last month, there were a few improvements to Hieroglyph sitting in the master branch, awaiting a release. Now that PyCon is over, I’ve cut the Hieroglyph 0.5.5 release. This is primarily a bug fix release, and it feels good to fix a bunch of issues that I discovered as I used Hieroglyph to develop and present Effective Django.

In addition to fixing half a dozen bugs, I also reviewed and revised almost all of the documentation for this release. Asheesh used Hieroglyph for his talk on web scraping at PyCon last week, and it was really interesting to get feedback from him about what worked and what was confusing. As a result, there’s a new Getting Started guide. There’s still work to be done, in particular in the Advanced Usage document; hopefully that will get rewritten and expanded soon.

Asheesh’s feedback demonstrated to me how little I know about why people use (or don’t) use Hieroglyph, and what’s difficult or confusing to them that I take for granted. If you’ve used Hieroglyph, thought about it and rejected it, or tried it and been frustrated, I’d like to hear about your experience. You can email me at nathan@yergler.net, or ping me on Identi.ca or Twitter: @nyergler

author:Nathan Yergler
tags:hieroglyph, sphinx, rst

Tut: Easier Tutorial Documentation with Sphinx

The PyCon sessions wound down today, so I’m finally coming up for air. This year I presented Effective Django, which evolved out of last year’s PyCon presentation and my PyOhio 2012 talk. As I prepared my PyCon talk last year, I started building Hieroglyph, which makes it easy to build HTML-based slides using Sphinx. This year I was preparing a different kind of presentation: a tutorial. As I started putting it together, I realized that tutorial-style documents differ from the previous presentations and documentation I’ve written.

In the past I used Sphinx code blocks in my documents, and then used the doctest builder to verify that they were written correctly. With a tutorial, however, I was putting together a demo application, and wanted to include code directly from that. Sphinx has the literalinclude directive, but that wasn’t quite enough: I was using git to manage the sample source repository, so what I really wanted to do was include code from that repository at a particular point in time.

I didn’t want to just copy and paste the code from the Python source into the ReStructured Text files: I did that briefly, and found it difficult to keep in sync as my thinking about the code evolved. I’d copy and paste, write some more text, realize I needed to make a change to the sample code, and then need to go back and change it in two places.

To solve this problem, I wrote Tut. Tut is a Sphinx extension that provides a simple directive, checkpoint. The checkpoint directive switches a git repository to a particular point in time: a branch, tag, or SHA; basically anything you can git checkout.

I used tags for Effective Django, so Tut also includes a script to help manage those. The script installs a post-rewrite hook in your git repository, so that if you need to reorder your commits your tags will be moved to the new SHAs. This can be useful if you find a bug and want to change it (“back in time”), or decide to reorder parts of your tutorial source.

I think Tut is a pretty handy little extension: it allowed me to use Sphinx’s built in inclusion directives in my documents, and eliminated work that took my focus off of actually creating content. You can find it on PyPI, and the source is available on github.

author:Nathan Yergler
tags:sphinx, rst, hieroglyph, tut

flymake with Sphinx

Working on my PyCon tutorial (next week!), I’ve been spending a lot of time in Emacs editing reStructured Text documents. I use Sphinx and Hieroglyph to generate the HTML, the slides, and the PDF from a single source, which make it easy for me to keep everything in sync. flymake is an Emacs mode that’s designed to do syntax or spell checking as you work. The name reveals its roots: in its simplest form, it just runs make for your project.

I was tired of flipping over to the shell to re-build the Sphinx project, so I decided to enable flymake for .rst files and see what happened. The flymake-allowed-file-name-masks variable has a list of regular expressions to flymake commands, so I added the following element to the list:

("\\.rst\\'" flymake-simple-make-init)

That was enough to get flymake to invoke the Makefile, and then I just needed to add the target it looks for: check-syntax. I added the following target to my Sphinx project Makefile:

        $(SPHINXBUILD) -n -N -q -b html $(ALLSPHINXOPTS) $(BUILDDIR)/
        $(SPHINXBUILD) -n -N -q -b slides $(ALLSPHINXOPTS) $(BUILDDIR)/slides

In my case I’m building both HTML and Slides from the Sphinx project, and I wanted both to be updated when I changed a file in Emacs. That did it.

Now all I wanted was automagic execution of make, but to my pleasant surprise, Sphinx’s warning and error output is compatible with flymake by default. Suddenly Emacs highlighted missing targets and directives with missing arguments in red. With flymake-cursor enabled, moving my cursor over one of those red lines showed me the Sphinx error below the mode-line.

There you have it: Sphinx just works with Emacs and flymake, you just need to turn it on.

author:Nathan Yergler
category:python, sphinx, emacs