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.