.. _contribdoc:

Documentation
=============

The source for `the documentation <https://docs.arbor-sim.org>`__ is found in the ``/doc`` subdirectory.
We use `Sphinx <https://www.sphinx-doc.org>`_ to build our docs.
You can add your contribution to the documentation in the same way you would contribute code; please see the :ref:`contribpr` section.

.. _contribdoc-tut:

Tutorials
---------

Documentation includes tutorials, which are :ref:`examples <contribexample>` with an associated
page under ``/doc/tutorial`` explaining the goal of the example and guiding the reader through the code.
We try to use the `literalinclude directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude>`
wherever possible to ensure the tutorial and example don't diverge.
Remember to update the line numbers whenever you update the examples in the tutorial.

Update policy
-------------

How to we decide if documentation is good? By observing how effectively it is used
in practice. If a question on Arbor (regardless of medium) is satisfactorily
resolved (on both sides!) with a pointer to the (relevant section in the) docs,
the documentation is good. If, on the other hand, an explanation is needed, the
documentation is bad.

If you found the documentation to be insufficiently clear or elaborate, you must
consider this a bug and find or file an `issue <https://github.com/arbor-sim/arbor/issues>`__ and if you are able, make a :ref:`pull request <contribpr>`.

.. _contribdoc-namingconventions:

Labels and filename conventions
-------------------------------

Although it is not absolutely essential to do so, we try to keep to the following conventions
for naming files and labels, with the goal of making it easy to construct one from the other
such that you don't have to remember or look anything up. We try to cross-link where we can,
which means we label where we can, which translates to a large number of labels.

Wherever possible, observe:

* file names: avoid underscores as much as possible. E.g., `cpp/cable_cell.rst` -> `cpp/cablecell.rst`.
* page-level labels in each file: the path concatenated without spaces. E.g. `cpp/cablecell.rst` -> `cppcablecell`.
* heading labels in a file: `pagelevel-sectionname`. Feel free to slugify long headings.
  E.g. the morphology section in the C++ cable cell docs could be `cppcablecell-morph`.

.. _contribdoc-lang:

Language
--------

Although the primary language of Arbor is C++, we use English for most of the non-code.
If in doubt, we recommend following the European Union's
`English style guide <https://ec.europa.eu/info/sites/info/files/styleguide_english_dgt_en.pdf>`_.

In general we try to have a relaxed and concise approach to the language.
