The impact of Two!Ears on the research community will be the greater the easier the code can be used and extended by other researchers. To achieve this the documentation of the whole Two!Ears Auditory Model is as important as the code itself. This means we are not only working constantly on our code base, but on the documentation as well.
This section explains how we should write the Two!Ears documentation from both a technical and a writing standpoint and includes:
Though Two!Ears’ documentation is intended to be read as HTML or PDF at http://twoears.eu/doc/, we edit it as a collection of text files for maximum flexibility. These files live in the Two!Ears documentation repository.
If you’d like to start contributing to our docs, clone this repository and get started:
$ git clone https://github.com/TWOEARS/documentation.git
For help on how to work with git, see Development using git.
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 -A web=0 ../_build 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
for every available release tag of the documentation.
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.
If you have existing documentation in LaTeX you can convert it to restructured text with pandoc:
pandoc -f latex -t rst -o outfile.txt infile.tex
Here are some style guidelines on commonly used terms throughout the documentation:
|TwoEars|– when referring to the project in general, this will be automatically replaced by Two!Ears
|TwoEarsModel|– when referring to the complete auditory model, this will be replaced with the text Two!Ears Auditory Model.
|BinSim|– when referring to the binaural simulator module of the Two!Ears Auditory Model, this will be automatically replaced by Binaural simulator.
|AFE|– when referring to the auditory front-end module of the Two!Ears Auditory Model, this will be automatically replaced by Auditory front-end.
|blackboard|– when referring to the blackboard architecture module of the Two!Ears Auditory Model, this will be automatically replaced by Blackboard system.
|robot|– when referring to the robot platform of the Two!Ears Auditory Model, this will be automatically replaced by Robotic platform.
|database|– when referring to the database of the Two!Ears Auditory Model, this will be automatically replaced by Database.
|amtoolbox|– when referring to the Auditory Modelling Toolbox, this will be automatically replaced by Auditory Modeling Toolbox.
Matlab– when referring to the language, capitalise Matlab.
initialise, etc. – use the British “ise” suffix, not “ize.”
These automatic replacement are defined in the file
acronyms are defined in
acronyms.py, see Using acronyms.
These guidelines regulate the format of our reST (reStructuredText) documentation and provide tips for writing them:
In section titles, capitalise only initial words and proper nouns.
Wrap the documentation at 80 characters wide, unless a code example is significantly less readable when split over two lines, or for another good reason.
The order of headings is the following:
======= Section ======= Subsection ---------- Subsubsection ~~~~~~~~~~~~~ Paragraphs ^^^^^^^^^^
The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:
To remove ``README.md`` execute ``rm README.md``...
Isn’t nearly as helpful as:
To remove :file:`README.md` execute :command:`rm README.md`...
This is because Sphinx will generate proper links for the latter, which greatly helps readers. There’s basically no limit to the amount of useful markup you can add.
The file ending of the reST files should be
*.rstthis will force github to display them as raw text files. The downside is that you have to tell your editor that you are editing a reST file –
:setf rstin vim.
A figure should always start with a label that can be later used to reference to
the figure. This label should always start with
After that the figure with the actual image file is added. The image
should be provided as a
png-file and stored in a
.. _fig-super-result: .. figure:: img/super-results.png :align: center Figure caption explaining the results. Text in which the :numref:`fig-super-result` is referenced in.
Like a figure a table should always start with a label for referencing and gets a caption before the actual table:
.. _tab-super-result: .. table:: Caption of the super result table. =============== =============== =============== Column1 heading Column2 heading Column3 heading =============== =============== =============== 1 2 3 1 2 3 1 2 3 =============== =============== =============== Text in which the Table :ref:`tab-super-result` is referenced in.
There is another way to define the same table:
.. _tab-super-result: .. table:: Caption of the super result table. +-----------------+-----------------+-----------------+ | Column1 heading | Column2 heading | Column3 heading | +=================+=================+=================+ | 1 | 2 | 3 | +-----------------+-----------------+-----------------+ | 1 | 2 | 3 | +-----------------+-----------------+-----------------+ | 1 | 2 | 3 | +-----------------+-----------------+-----------------+
This is especially interesting for more complex tables.
Line breaking is unfortunately not handled automatically in a table. Instead, the table will be stretched out to fir the content in one line per cell. You can add line breaks manually by inserting blank lines:
.. _tab-super-result: .. table:: Caption of the super result table. +-----------------+-----------------+--------------------+ | Column1 heading | Column2 heading | Column3 heading | +=================+=================+====================+ | 1 | 2 | text in line1 | | | | more text in line1 | | | | | | | | text in line2 | | | | | | | | text in line 3 | +-----------------+-----------------+--------------------+ | 1 | 2 | 3 | +-----------------+-----------------+--------------------+ | 1 | 2 | 3 | +-----------------+-----------------+--------------------+
This will result in
|Column1 heading||Column2 heading||Column3 heading|
text in line1 more text in line1
text in line2
text in line 3
If you want to add a reference to another section, figure, or table you can do it the following way:
See results in :numref:`fig-super-result` in Section :ref:`sec-results`.
This requires of course that the labels for the figure and the section is set accordingly:
.. _sec-results Results ------- .. _fig-super-results .. figure:: img/results.png Super results from the experiment.
If you do the referencing as shown in the first code listing the
:ref:`label` will be replaced by the title of the section or
the number of the figure.
If you have an acronym like HRTF, you should define it in the
file in the following way:
.. |HRTF| replace:: :abbr:`HRTF (head-related transfer function)`
In the text you then simply write
|HRTF|. This will transform to acronym
like HRTF in the HTML version and will be written out only the first time in
the PDF version of the documentation. If you need the plural form you have to
|HRTF|\ s which will translate into HRTFs.
Our policy for new features is:
The actual documentation present in the master branch of the development repository should be always corresponding to the actual code/data that is present in the master branches of the single module repositories.
Before you commit your docs, it’s a good idea to run the spelling checker. You’ll need to install a couple packages first:
Then from the
doc directory, run
make spelling. Wrong words (if any)
along with the file and line number where they occur will be saved to
If you encounter false-positives (error output that actually is correct), do one of the following:
- Find synonyms that the spell checker recognises.
- If, and only if, you are sure the word you are using is correct - add it
doc/spelling_wordlist(please keep the list in alphabetical order).