Using Unicode with Sphinx, reStructuredText, and PDF Output

I’m working on updating my book, and besides actually writing the content one of the things I have to do is generate new LaTeX files to deliver to the publisher. I’ve written about my toolchain elsewhere, so I won’t repeat all of that information here. The short version is that I use Paver to drive Sphinx to convert reStructuredText input files to HTML for the website, LaTeX for the compositor at Pearson, and PDF for reviewers. Since the updated version covers Python 3, and one of the key benefits of Python 3 is better Unicode support, I want to include some characters outside of the normal ASCII set in my examples.

When you ask Sphinx’s latex builder to generate LaTeX output the result is a directory with a *.tex file containing your content and some other files with all of the parts you need to convert that LaTeX to other formats, including a Makefile with instructions for building PDF and DVI. By default that Makefile uses pdflatex to convert the *.tex output files it writes to PDF. My article for the random module includes an example of shuffling a card deck. The Python 2 version used letters to represent the card suits, but for Python 3 I switched to using Unicode symbols like what would appear on the cards. Making that work for HTML was easy, but the PDF output proved trickier.

Continue reading Using Unicode with Sphinx, reStructuredText, and PDF Output

sphinxcontrib-paverutils 1.7 – Sphinx/Paver integration

sphinxcontrib-paverutils provides an alternative integration of
Sphinx and Paver. It supports calling Sphinx from within Paver using
multiple configurations, and does not assume you only want to build
HTML output.

What’s New?

  • Newer versions of sphinx try to exit when main() is done, so
    trap that exit code and return it.
  • Build universal wheels of releases.

sphinxcontrib-paverutils 1.6

What is sphinxcontrib-paverutils?

sphinxcontrib-paverutils provides an alternative integration of
Sphinx and Paver. It supports calling Sphinx from within Paver using
multiple configurations, and does not assume you only want to build
HTML output.

What’s New in This Release?

  • Improve Python 3 support
  • Clean up packaging using pbr
  • redefine cog to allow it to run on specific input file(s)

new project: sphinxcontrib-paverutils

Kevin Dangoor’s Paver includes basic integration for Sphinx, the
excellent document production toolkit from Georg Brandl. As I have
written before, however, the default integration didn’t quite meet my
needs for producing different forms of output from the same inputs.

Georg has opened the sphinxcontrib repository on BitBucket for
developers who want to collaborate on providing unofficial extensions to
Sphinx, so I decided to go ahead and package up the alternate
integration I use and release it in case someone else finds it helpful.
The result is sphinxcontrib.paverutils.