Skip to content

Writing documentation

Jump to bottom
Carl Simon Adorf edited this page Dec 12, 2019 · 34 revisions

Improving the documentation to AiiDA is both straightforward and valuable.

AiiDA uses Sphinx. See:

NOTE: The documentation is currently undergoing a major revision to reflect the structure and guidelines outlined here.

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:

  • 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 (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 guide for all AiiDA components (Python API, CLI, RESTful API, etc.) which is oriented around the actual code and should use highly consistent language (information-oriented).

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 10-30mins.
  • 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

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, that includes 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 that it's 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.

Finally, the language in the reference documentation 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. There should be one sentence per line and otherwise no manual line wrapping, because it makes it significantly easier to create and review consistent 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.
  3. User under- (and sometimes overlining) to create section headers (not exceeding the header length) followed by an empty line and with the following convention (adapted from here):
    • # with overline for the global title
    • * with overline for chapters
    • = for sections
    • - for subsections
    • ^ for subsubsections
  4. Paragraphs should be separated by two empty lines, but not more.
  5. Use the * symbol for itemized lists.
  6. For anything else that is not explicitly specified here, authors should follow the Python style guide for RestructuredText for documentation.

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
"""
Clone this wiki locally