Writing documentation

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:

Getting the raw documentation

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.

Getting 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

or directly sphinx-build -b html -A web=0 ../_build if make is not working for you. The result can be explored under _build/html/latest/index.html.

Note

To generate the version presented on the official Two!Ears documentation site you have to run make dirhtml 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.

Converting existing documentation

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

Commonly used terms

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.
  • localise, initialise, etc. – use the British “ise” suffix, not “ize.”

Note

These automatic replacement are defined in the file conf.py, acronyms are defined in acronyms.py, see Using acronyms.

Guidelines for reStructuredText files

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 *.txt instead of *.rst this 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 rst in vim.

Add a figure

A figure should always start with a label that can be later used to reference to the figure. This label should always start with fig-. After that the figure with the actual image file is added. The image should be provided as a png-file and stored in a img/ folder:

.. _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.

Add a table

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

Table 21 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

Dealing with referencing throughout the document

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 Fig. and the number of the figure.

Using acronyms

If you have an acronym like HRTF, you should define it in the acronym.py 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 write |HRTF|\ s which will translate into HRTFs.

Documenting new features

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.

Spelling check

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 _build/spelling/output.txt.

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 to doc/spelling_wordlist (please keep the list in alphabetical order).