Sphinx

Sphinx is a Python-based typesetting and layout tool for authors. Specifically, it is a ReST (Re-Structured Text) markdown schema intended to produce both print and electronic copies of text. It is widely used in technical documentation (it's the basis for the popular Read the Docs documentation website), but also for works of fiction, academia, and more.

Strengths [Weaknesses]

Familiar

Markdown is a simple, minimally-structured format that is easy to write and easy to read even in its un-processed state. There are only a few rules to remember, and they can be kept close at hand in a cheatsheet.

[Ex]Portable

One your text is in ReST format, it is structured and predictable. This probably means that if there is another format (html, epub, pdf, ps, plain text, rtf, odt, and so on) that you want to output to, you can convert to it from ReST. There isn't much ambiguity about ReST, and the post-processing options are many.

Weaknesses [Strengths]

Simple

ReST can be too simple for some people's needs. It concentrates on simplicity, but in so doing it sacrifices flexibility in layout and structure. Sometimes there are hacks around its limitations, but these hacks might be more trouble than they are worth when compared to just starting out with XML in the first place.

Style

Since your text is processed by a Python processor that you probably are not going to bother customising, the look and feel of the output is probably going to look like all the output of all other Sphinx output. You can modify the templates and use alternate themes, but if you are looking for the freedom and flexibility of raw HTML, this might not be the best option for you.

Install

Install Sphinx from http://slackbuilds.org, but mind that the “S” is a capital “S”. There is a search engine called “sphinx” (with a small “s”); you are looking for the Python text processor, not a search engine.

Sphinx depends upon several other Python libraries, so install those first.

Quickstart

Here is a basic summary, featuring a severely limited set of functionality for the sake of brevity:

To create a new Sphinx project, type:

$ sphinx-quickstart

This auto-start script asks a few questions about your project (title, author, version number, and so on). Most questions can be answered with the default responses, with two exceptions.

Choose Yes when prompted about a separate source and build directory.

Separate source and build directories (y/n) [n]: y

Choose Yes when prompted for epub compatibility (unless you absolutely do not want epub compatibility for that project).

Do you want to use the epub builder (y/n) [n]: y

Above all else, answer Yes for a Makefile. You can refuse the Windows batch file , but accept the Unix Makefile; without it, the build process is slightly less convenient.

In the end, you are left with a directory containing a Makefile, a build and a source directory. In the source directory are two essential Sphinx files:

  • index.rst
  • conf.py

The conf.py file, containing project-specific options, has been configured for you via the sphinx-quickstart script. As you learn more about Sphinx, you might have the occasion to modify the options in the file, but for now the defaults suffice.
The index.rst contains the skeleton of your project so far. It defines a front page (itself), a table of contents containing itself, an index, and a search field.

This is the basic code:

Welcome to Slackermedia's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Build this frightfully simple project from the root level of the project directory:

$ ls -1
Makefile
build
source
$ make html

View the rendered page in the build/html directory.

$ firefox ./build/html/index.html
The most basic Sphinx project possible.

Advanced Techniques

The usual means of using Sphinx is to create new documents within the source directory, each of which contains the contents of your book. Add the filenames to the index.rst file in the order you want them to appear. For instance, if you write a three chapter book, keeping each chapter in a separate file, then your index.html page might be:

Great Novel
=============

Contents:

.. toctree::
   :maxdepth: 2
   chapter1.rst
   chapter2.rst
   chapter3.rst
   colophon.rst

* :ref:`search`

In large works, there is an advantage to keeping your writing modular. Structuring your work such that each chapter is an individual file allows your text editors to load and work on them faster, and makes rearranging the order of the chapters trivial.

ReST is a simple format, and once you know the theory it's easy to use. The formatting is often intuitive; for instance, to create a top-level heading, “underline” a title line with equal signs:

This is a Title
================

It was a **dark** and *stormy* night.

Sub-Heading
------------

A shot rang out, a maid screamed, a pirate ship appeared on the horizon.

Typeface is stylised with simple inline markup (or markdown, technically):

**bold** text
*italics* text
``monospace`` text

The official Sphinx overview of ReST markdown is located on their site at http://sphinx-doc.org/rest.html, but a better re-interpretation of that is located at http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html

Makefile

The Sphinx default Makefile defines several kinds of output, including HTML for webpages, XML, plain text, the popular open source ebook format epub, and more.

To build, the command must be run from the root level of your project, and the command is just make along with the format you want to have built:

$ make epub

It's a great way to produce professional-looking and well-managed documentation easily.

R S Q