Get started with Sphinx

Two!Ears’ documentation uses the Sphinx documentation system, which in turn is based on docutils. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format.

To actually build the documentation locally, you’ll currently need to install Sphinx – pip install Sphinx or sudo apt-get install python-sphinx should do the trick. Under Windows you first have to install python, which should also install pip and you can install Sphinx then also via pip. Otherwise have a look at the official installation guide.

Caution

We need sphinx version 1.3 or later in order to use the setting of line number start value for code blocks. It could be that you have to use pip to get this version.

Then, building the HTML is easy; just run:

make html-preview

or directly sphinx-build -b html -d _build/doctrees . _build/html-preview if make is not working for you. The result can be explored under _build/html-preview/index.html.

Note

To generate the version presented on the official Two!Ears documentation site you have to run make html. As the documentation is hosted and automatically built by Read the Docs you don’t need to do this.

To get started contributing, you’ll want to read the reStructuredText Primer. After that, you’ll want to read about the Sphinx-specific markup that’s used to manage meta data, indexing, and cross-references. A very detailed documentation is provided at the Sphinx/Rest Memo site.