Sphinx (but not the Search Engine)

For a reStructuredText Primer, see http://sphinx.pocoo.org/rest.html.

Sections

Sphinx doesn’t care what punctuation you use for marking headings, but each new kind that it sees means one level lower in the outline. So,

=========
Heading 1
=========

Heading 2
---------

will correspond to

<h1>Heading 1</h1>
<h2>Heading 2</h2>

For consistency, this is what I’m using for headings in Zamboni:

=========
Heading 1
=========

Heading 2
---------

Heading 3
~~~~~~~~~

Heading 4
*********

Heading 5
+++++++++

Heading 6
^^^^^^^^^

Use two newlines prior to a new heading. I’m only using one here for space efficiency.

Sphinx Extras

Use :src:`path/to/file.py` to link to source files online. Example: settings.py.

Vim

Here’s a nice macro for creating headings:

let @h = "yypVr"