Guide for Writing Documentation

AiiDA-Tutorial uses Sphinx to create the documentation. See:

• a great introduction to ReStructured Text (RST) <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>_
• the official Sphinx documentation <http://sphinx-doc.org>_

Useful resources about writing good documentation

• The Documentation System
• Google developer documentation style guide – especially the notes about tone.
• The Documentation Compendium

Style guide

When writing documentation for sphinx in the reStructuredText Markup, authors should adhere to the following guidelines:

1. Write one sentence per line and otherwise no manual line wrapping to make easy to create and review diffs. All standard editors allow for dynamic line wrapping, and the line length is irrelevant for the rendered documentation in, e.g., HTML or PDF format.

2. File and directory names should be alphanumeric and all lower-case with underscores as word-separators. Example: entry_points.rst

3. Headers must be set in sentence-case. Example: "Entry points"

4. Under-/overline section headers (not exceeding the header length), followed by an empty line. We suggest the following convention (adapted from here):

   • # with overline for the global title
   • * with overline for chapters
   • = for sections
   • - for subsections
   • ^ for subsubsections

5. Separate paragraphs by one empty line, but not more.

6. Use the * symbol for itemized lists.

7. Use the code-block directive (.. code-block::) instead of a double colon to markup code segments (see also section "Code Segments" below).

For more guidance see the Python style guide for RestructuredText.

Code Segments

• Bash shell scripts should use bash

  .. code-block:: bash
  
      verdi node show 1

• Bash shell sessions (i.e. interactive) should use console

  .. code-block:: console
  
      $ verdi node show 1

Use # instead of $ to indicate a root prompt.

• Python scripts should use python

  .. code-block:: python
  
      from aiida import orm

• Python sessions (i.e. via verdi shell) should use ipython

  .. code-block:: ipython
  
      In  [1]: print("a")
      Out [1]: "a"

Updating the handwritten documentation

• Modify relevant doc strings or .rst files in the /docs/source/ folder (not in /docs/build)

• Add new .rst files to the relevant index.rst files (table of contents)

• Run make html in the /docs folder

• Open build/html/index.html to check the result

• | Fix warnings, if any.
  Note: The continuous integration tests on your PR will fail, if warnings are encountered while building the documentation.

References

Please add target links to all top/sub-level headings in the following format, e.g.,

.. _how-to:installation:backup:restore:

To reference them further in the text, write

:ref:`how-to:installation:backup:restore`

Naming conventions

• setup: one word, not "set up", e.g., "How to setup a computer."
• Python: Capitalized, not "python", because this is a name.
• UUID: Block capitalized.

Glossary

• User: Someone who uses the AiiDA top-level API.
• Plugin developer: Someone who develops AiiDA plugins.
• Core developer: Someone who contributes to the AiiDA core package.