Hieroglyph 0.6

I just uploaded Hieroglyph 0.6 to PyPI. This release contains a handful of new features, as well as fixes for a few bugs that people encountered. Some highlights:

  • Doug Hellmann contributed support for displaying presenter notes in the console using the note directive.
  • tjadevries contributed a fix for the stylesheet used when printing slides, which should prevent modern browsers from inserting a page break in the middle of a slide.
  • Slide numbering has been reimplemented, and received additional testing.
  • A hieroglyph-quickstart script has been added to make it easier to generate an empty project with hieroglyph enabled.

See the NEWS for the full details.

I’ve also started writing some automated tests for Hieroglyph. These are a little too involved to properly be called “unit tests”, but they’re being run using Travis CI now, which should help avoid regressions as I fix bugs in edge cases.

I spent a few days at OSCON about a week ago, and once again had the pleasure of attending Damian Conway’s “Presentation Aikido”. There are several things he talked about that I could be doing better with my talks. This release of Hieroglyph addresses one of them (quick fade or cut to the next slide, as opposed to the default slide left behavior). I’m working on what other changes I can make to Hieroglyph so that it’s dead simple to just write your slides, and maximize what your attendees take away.

author:Nathan Yergler
category:hieroglyph
tags:rst, hieroglyph, sphinx
comments:

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
category:hieroglyph
tags:hieroglyph, sphinx, rst
comments:

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
category:tut
tags:sphinx, rst, hieroglyph, tut
comments:

Hieroglyph Improvements

If you’re using Hieroglyph for generating slides with Sphinx, you may want to use the version in git rather than the release. A few things have landed there recently:

  • tjadevries contributed fixes for incremental slides in Chrome.

    It seems that a recent change in Chrome caused the incremental slide Javascript, which originated in the Google HTML5 Slides project, to stop working. master has a fix for that.

  • Proper pruning when autoslides are disabled.

    If you have autoslides turned off in a document, Hieroglyph will now properly prune the document when generating slides to only show explicit slide directives. This was broken in 0.5.

  • Fixed header sizing for slide directives.

    The slide directive allows you to specify a level attribute. This is supposed to be used for determining how to render the slide title (for example, a level of 2 should render the title as an <h2>). This was broken in 0.5, and is fixed now.

I’m using Hieroglyph for my PyCon tutorial, “Effective Django[1], but the way I’m using it is pretty different than it has been previously. The slides and HTML output differ more, so I’m not relying on automatic slide generation the way I was initially. I expect I’ll make a new release around PyCon (mid-March) when I’ve done an entire talk in this manner.

[1]I’ve started practicing my tutorial with the engineering team at Eventbrite in one hour chunks, once a week. I’ll probably post something about that experience once I have an opinion about how it works.
author:Nathan Yergler
category:hieroglyph
tags:sphinx, hieroglyph, rst
comments:

Hieroglyph 0.3.2: Slide Table and Interlinking

Since PyCon I’ve continued to think about how I can make slides from ReStructured Text documents and vice versa. I tend to write a lot of notes and text while I’m putting together a talk, and I like the idea of being able to keep slides and text output in sync. I’ve just a batch of changes to Hieroglyph, my tool for doing that. There’s some clean-up there — better handling of output paths when using things like blockdiag, code clean-up, etc — but there are two things I’m really excited about. First, two pull requests (one for Python 3 support, another for some documentation bugs), and second some new features that I think make Hieroglyph much more powerful.

Thinking about keeping slides and text (HTML) output in sync, it occurred to me there were probably times you’d want to easily switch between slides that provide an overview, and the HTML document for more details and context. Much of the work for 0.3.2 focused on enabling this interlinking. When enabled, Hieroglyph will add links to your HTML and Slide output that links to the other format. For HTML this can be enabled in the sidebar, as well as at the section level. For slides, the link is added next to each slide’s header, and shows up when you hover over the header. Check it out on the Hieroglyph documentation — just hover over any header and click the § link for the corresponding slides.

When I was working on my PyCon talk, I had anywhere from 50 to 70 slides in the deck at any given time (NB: yes, this is too many for a talk of that length). Navigating between them was challenging at times. The second feature I’ve added to Hieroglyph is designed to address this. When viewing a Hieroglyph presentation, you can now press the Escape key to see the Slide Table.

An example of the slide table in use for the Hieroglyph documentation (full size).

Press Escape again to return to the slide you were on, or click a slide to jump directly to it. You can try this with the Hieroglyph documentation slides.

Finally, what should really be considered the third new feature: expanded documentation. You can find expanded documentation on configuring Hieroglyph, styling your slides, etc in the docs online.

There are several additional things I’m working on for Hieroglyph. As Ilya points out in “All Presentation Software Is Broken”, web analytics are your “free lunch” if you use HTML-based slides. I plan to bake support for that directly into Hieroglyph. As I’m using Hieroglyph, I’m also realizing that slides don’t always correspond directly to sections in a document — sometimes (but not always) they’re a paragraph, list, or something else. Some way to indicate this may be helpful. If you find Hieroglyph useful (or interesting), let me know what you’d like to see.

date:2012-06-05 13:22:29
wordpress_id:2123
layout:post
slug:hieroglyph-0-3-2
comments:
category:projects
tags:hieroglyph, rst, slides