Sphinx documentation

Sphinx is a Python-based documentation system that allows writing documentation in a simple mark-up language called ReStructuredText, which can then be converted to html or to latex files (and then to pdf or postscript). See [sphinx] for general information, [sphinx-documentation] for a complete manual, and [sphinx-rst] or [rst-documentation] for a primer on ReStructuredText. See also [sphinx-cheatsheet].

Although originally designed for aiding in documentation of Python software, it is now being used for documentation of packages in other languages as well. See [sphinx-examples] for a list of other projects that use Sphinx.

It can also be used for things beyond software documentation. In particular, it has been used to create the class note webpages that you are now reading. It was chosen for two main reasons:

1. It is a convenient way to create a set of hyper-linked web pages on a variety of topics without having to write raw html or worry much about formatting.
2. Writing good documentation is a crucial aspect of high performance scientific computing and students in this class should learn ways to simplify this task. For this reason many homework assignments must be “submitted” in the form of Sphinx pages.

The easiest way to learn how to create Sphinx pages is to read some of the documentation and then examine Sphinx pages such as the one you are now reading to see how it is written. You can do this with these class notes or you might look at one of the other [sphinx-examples] to see other styles.

Note that any time you are reading a page of these class notes (or other things created with Sphinx) there is generally a menu item Show Source (on this page it’s on the left, under the heading This Page) and clicking on this link shows the raw text file as originally written. Try this now.

It is possible to customize Sphinx so the pages look very different, as you’ll see if you visit some other projects listed at [sphinx-examples].

Using Sphinx for your own project

If you want to create your own set of Sphinx pages for some project, it is easy to get started following the instructions at [sphinx], or for a quick start with a different look and feel, see [sphinx-sampledoc].

Using Sphinx to create these webpages

If you clone the hg repository for this class (see Mercurial (hg)), you will find a subdirectory called sphinx, containing a number of files with the extension .rst, one for each webpage, containing the ReStructuredText input. To create the html pages, first make sure you have Sphinx installed via:

$ which sphinx

(see Downloading and installing software for this class) and then type:

$ make html

This should process all the files (see Makefiles) and create a subdirectory of sphinx called _build/html. The file _build/html/index.html contains the main Table of Contents page. Navigate your browser to this page using Open File on the File menu of your browser.

Or you may be able to direct Firefox directly to this page via:

$ firefox _build/html/index.html

Making a pdf version

If you type:

$ make latex

then Sphinx will create a subdirectory _build/latex containing latex files. If you have latex installed, you can then do:

$ cd _build/latex
$ make all-pdf

to run latex and create a pdf version of all the class notes.

Further reading

See [sphinx] for general information, [sphinx-documentation] for a complete manual, and [sphinx-rst] or [rst-documentation]. See also [sphinx-cheatsheet].

See [sphinx-sampledoc] to get started on your own project.