Writing documentation

Improving the documentation to AiiDA is both straightforward and valuable.

AiiDA uses Sphinx. See:

• a great introduction to ReStructured Text (RST)
• the official Sphinx documentation

Note: A convenient way to modify the documentation is to

pip install tox
tox -e py38-docs-live  # automatically recompiles docs when changes are detected

Useful resources about writing good documentation

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

How the AiiDA documentation is organized

Basic structure

The AiIDA documentation is aimed at new and experienced users of the AiiDA infrastructure as well as developers with the aim to teach, explain, and to serve as a reference. The documentation structure is modeled after the django documentation as outlined in this blog article, and is divided into the following sections:

• Getting started (intro/) - Landing page for new users, should provide motivation, code snippets, and links to the various resources, including on how to install the package, test it online, and the tutorial.
• Tutorial (tutorial/) - Teaches new users how to generally use AiiDA (strictly learning-oriented).
• How-to Guides (howto/) - Provides concrete recipes on how to achieve certain goals with AiiDA (problem/goal-oriented).
• Topics (topics/) - More detailed explanations on AiiDA concepts and in-depth discussion of specific AiiDA components. This section provides more background and should be informative for new and advanced users.
• Reference (reference/) - A complete reference for all AiiDA components (Python API, CLI, RESTful API, etc.) which focuses on the actual implementation/code, should use highly consistent language (information-oriented).
• Development (development/) - Guidelines relevant to contributors to the aiida-core package.

Intro

The intro section (likely titled as "Getting started") is designed to be the landing area for new (and skeptical) users. The first page is the designated landing page and must provide enough information about the motivation and scope of the AiiDA software, that a new user can make a decision about whether to test the software in about half a minute.

Other pages include instructions on how to install AiiDA, (planned) test it online, a description of how the documentation is organized, and generally links to the sections. Links should be designated by user group, for example: "New users should start with the tutorial.".

Tutorial

The tutorial is aimed at new users, that means users who have never worked with AiiDA before or who have only very limited experience using AiiDA in their own problem space.

The tutorial is primarily learning-oriented and must adhere to the following limitations:

• single path - while there may be multiple ways of accomplishing the same goal, the tutorial presents only one single path to demonstrate AiiDA functionality
• no requirements - The tutorial works without the need to either install additional software, download data, or additional configuration.
• concise - The tutorial provides only minimally required explanations concerning the AiiDA concepts and otherwise relies on links to other parts of the documentation.
• short - There should be a reasonable expectation that a new or inexperienced user can complete the tutorial in 30mins (10mins for an experienced user/developer).
• small steps - Each step within the tutorial must provide immediate feedback and should only take 1-2mins to complete

The tutorial goals are to teach new users, that AiiDA

• is implemented in Python and provides both a Python and a command line interface,
• enables them to implement computational workflows that are executed locally or on a HPC cluster with a scheduler,
• helps them to solve typical problems relevant to scientific workflows, including discoverability and reproducibility,
• can execute workflow transformation steps that are implemented in Python,
• can integrate external tools through the implementation of Plugins,

It further demonstrates how to use AiiDA to

• implement a basic reproducible workflow in Python,
• discover and retrieve data from the AiiDA database,
• retrieve provenance data from the AiiDA database.

How-to guides

The how-to guides provide concrete goal-oriented recipes for how to achieve certain tasks with AiiDA. Examples include how to implement a workflow, and how to discover and extract data. The how-to guides should provide concrete steps, but do not have to be as detailed as a tutorial and further are not required to demonstrate a specific recipe from start to finish, meaning that there is some expectation that users are generally familiar with AiiDA.

The how-to guides should be

• concrete - a recipe should focus on a specific task and should show concrete steps (including code examples) on how to implement them
• concise - explanations should be limited, links to the topics sections are preferred
• demonstrate best practices - contrary to the tutorial, examples shown here should adhere to actual best practices that users should follow

The How-To section titles should largely remain jargon free as they are supposed to be browsable and searchable by new users, however in some exceptional circumstances specific keywords can be added to the section title to make the section more easily findable for more experienced users. The order of sections and subsections within this chapter should roughly follow how commonly we assume a user would encounter the addressed problem, i.e., from more common to less common.

Topics

The topics section is understanding-oriented and aimed at users who are generally familiar with AiiDA and provides more in-depth explanations on concepts and design decisions for AiiDA. They may include discussions on alternative approaches, provide detailed background information, and can be abstract.

The topics section is fairly flexible in terms of how detailed certain topics are discussed and whether code examples are helpful or not, however concrete recipes should be linked to as part of the how-to section.

Reference

The reference section is information-oriented and provides a comprehensive description of all components of AiiDAs API, including the CLI, the Python API, the RESTful API, and all other APIs which may be implemented in the future. The first priority for the reference documentation is to be accurate and complete. Because of this, the majority of the reference section content should be auto-generated directly from the code, e.g., from doc-strings.

The language in the reference should be highly consistent, similar to an encyclopedia. Explanations and code examples should be kept to the absolute minimum. It can be assumed that readers are familiar with AiiDA concepts.

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.

Updating the automatic API documentation

The AiiDA documentation includes an documentation of the entire AiiDA API that is extracted automatically from the AiiDA source code, namely from the python docstrings of modules, functions and classes.

If the docstrings are formatted appropriately, sphinx will do most of the work for you:

"""
Description of the function.

:param parameter: some notes on input parameter
:type parameter: str

:return returned: some note on what is returned
:rtype: str

:raises ValueError: Notes on the type of exception raised
"""

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`

Useful resources

• You can use the tool graph easy to create very simple ascii provenance graphs.

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.