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
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.
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:
sphinx-build -b html -d _build/doctrees . _build/html-preview if
make is not working for you. The result can be explored under
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.