Sphinx Introduction for LLVM Developers

This document is intended as a short and simple introduction to the Sphinx documentation generation system for LLVM developers.

Quickstart

To get started writing documentation, you will need to:

1. Have the Sphinx tools installed.
2. Understand how to build the documentation.
3. Start writing documentation!

Installing Sphinx

You should be able to install Sphinx using the standard Python package installation tool easy_install, as follows:

$ sudo easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.1.3
... more lines here ..

If you do not have root access (or otherwise want to avoid installing Sphinx in system directories) see the section on Installing Sphinx in a Virtual Environment .

If you do not have the easy_install tool on your system, you should be able to install it using:

Linux

Use your distribution’s standard package management tool to install it, i.e., apt-get install easy_install or yum install easy_install.

Mac OS X

All modern Mac OS X systems come with easy_install as part of the base system.

Windows

See the setuptools package web page for instructions.

Building the documentation

In order to build the documentation, all you should need to do is change to the docs directory and invoke make as follows:

$ cd path/to/project/docs
$ make html

Note that on Windows there is a make.bat command in the docs directory which supplies the same interface as the Makefile.

That command will invoke sphinx-build with the appropriate options for the project, and generate the HTML documentation in a _build subdirectory. You can browse it starting from the index page by visiting _build/html/index.html.

Sphinx supports a wide variety of generation formats (including LaTeX, man pages, and plain text). The Makefile includes a number of convenience targets for invoking sphinx-build appropriately, the common ones are:

make html

Generate the HTML output.

make latexpdf

Generate LaTeX documentation and convert to a PDF.

make man

Generate man pages.

Writing documentation

The documentation itself is written in the reStructuredText (ReST) format, and Sphinx defines additional tags to support features like cross-referencing.

The ReST format itself is organized around documents mostly being readable plaintext documents. You should generally be able to write new documentation easily just by following the style of the existing documentation.

If you want to understand the formatting of the documents more, the best place to start is Sphinx’s own ReST Primer.

Learning More

If you want to learn more about the Sphinx system, the best place to start is the Sphinx documentation itself, available here.

Installing Sphinx in a Virtual Environment

Most Python developers prefer to work with tools inside a virtualenv (virtual environment) instance, which functions as an application sandbox. This avoids polluting your system installation with different packages used by various projects (and ensures that dependencies for different packages don’t conflict with one another). Of course, you need to first have the virtualenv software itself which generally would be installed at the system level:

$ sudo easy_install virtualenv

but after that you no longer need to install additional packages in the system directories.

Once you have the virtualenv tool itself installed, you can create a virtualenv for Sphinx using:

$ virtualenv ~/my-sphinx-install
New python executable in /Users/dummy/my-sphinx-install/bin/python
Installing setuptools............done.
Installing pip...............done.

$ ~/my-sphinx-install/bin/easy_install sphinx
... install messages here ...

and from now on you can “activate” the virtualenv using:

$ source ~/my-sphinx-install/bin/activate

which will change your PATH to ensure the sphinx-build tool from inside the virtual environment will be used. See the virtualenv website for more information on using virtual environments.