Monday, December 2, 2013

The e-Writing Jungle Part 3: Web-Based e-books Using Python / Sphinx

In the previous Parts 1 and 2, I essentially dealt with two extremes: (1) LaTeX to pdf to web, and (2) raw HTML (however arrived at) with math rendered by MathJax. Now let's look at something of a middle ground: the Python package, Sphinx, for producing e-books.

Part 3: Python / Sphinx

Parts 1 and 2 of Quantitative Economics, by Stachurski and Sargent, are great routes into Python for economists. There's lots of good comparative discussion of Python vs. Matlab or Julia, the benefits of public-domain, open-source code, etc. And it's always up to the minute, because it's an on-line e-book! Just check it out.

Of course we're interested here in e-books, not Python per se. It turns out, however, that Stachurski and Sargent is also a cutting-edge example of a beautiful e-book. It's effectively written in Python using Sphinx, which is a Python package that started as a vehicle for writing software manuals. But a manual is just a book, and one can fill a book with whatever one wants.

Sphinx is instantly downloadable, beautifully documented (the documentation is written in Sphinx, of course!), open source, and public domain (licensed under BSD). ReStructuredText is the powerful markup language. (You can learn all you need in ten minutes, since math is the only complicated thing, and math stays in LaTeX, rendered either by JavaScript via MathJax or as png images, your choice.) In addition to publishing to HTML, you can publish to LaTeX or pdf.

Want to see how Sphinx performs with math even more dense than Stachurcski and Sargent's? Just check, for example, the Sphinx book Theoretical Physics Reference.  Want to  see how it performs with graphics even more slick than Stachurcski and Sargent's? Just check the Matplotlib Documentation. It's all done in Sphinx.

Sphinx is a totally class act. In my humble opinion, nothing else in its genre comes close.