Documentation how-to

Tip

Do you have ideas for corrections and improvements of our user documentation? In this page you will learn how to:

  • contribute to our documentation
  • edit the docs with Sphinx language
  • build the docs on your laptop

Our documentation is hosted on Github and is written in Sphinx restructed text. Behind the scenes we use ReadTheDocs to publish it automatically. You can contribute either directly to our Grid Github repo or send an email to our helpdesk with your remarks and we will change the documentation ourselves. Any contribution is welcome!

The rest of this page explains how to to submit your changes directly through Github.

Contribute through GitHub

In case that you have a GitHub account and a little knowledge of git (see GitHub’s git cheat sheet), you can try submitting your changes directly to our repository. Here is what you have to do:

  1. Fork our Grid Github repo
  2. Git pull your fork
  3. Edit with Sphinx language the files with your changes
  4. Build the documentation locally to preview the changes
  5. Commit and push your changes back to your fork
  6. Create a pull request to inform us of your changes
  7. After we’ve reviewed and accepted your work, we will merge your commits and the documentation will be updated automatically

Edit with Sphinx language

When you contribute directly to our Github repo we ask you to write the changes in Sphinx language. The philosophy of Sphinx documentation is that content is stored in files that can be easily read and edited by humans, in a format called restructured text, with the file extension .rst. Using a simple grammar, text can be styled. The document is structured using special tags; using these tags, documentation can be split into multiple files, and you can cross-reference between files and build indexes.

Although Sphinx is quite intuitive, we have created a simple Sphinx cheatsheet to help you use the Sphinx syntax:

Build the documentation locally

Because the syntax of the files is human readable, you can edit the files using your favourite text editor. Once you are done editing, you can generate documentation in various formats, such as HTML or epub. While you can edit the pages on virtually any system, it is recommended to preview your changes before publishing them.

There are different ways to generate the HTML documentation from source and review your changes:

Note that you only need to use one of the options mentioned above. Using Docker is the preferred way, as this mimics the ReadTheDocs build system closest. GitHub edit/preview on the other hand is good enough for minor, textual changes, but is otherwise the least preferred option.

Below you will find information for each of the methods.

Docker image

This is the preferred option to build and test your changes. It tries to build the documentation the same way as readthedocs.org.

  • Install Docker image

  • Once the Docker image is ready, find the following script inside your Github fork and run it to build your documentation. Provide an output location (default: ./build) and the Docker image name (default: readthedocs/build):

    ./build.sh
    

Optionally you can provide an output location (default: ./build) and the Docker image name (default: readthedocs/build):

./build.sh /alternative/output/path/ docker_image_alternative_name

Example:

./build.sh mybuild readthedocs/build:latest

Note

For Mac OS X, use ./build_mac.sh instead.

Sphinx local installation

For the Sphinx documentation setup locally you will need to:

  • Install Sphinx sphinx_install

  • To generate HTML documentation, use the command:

    make html
    

which will generate static pages in the build-directory as long as you have the software Sphinx installed locally.

Github edit/preview

For small changes you can edit a page directly from your GitHub fork webview. The preview button does not give a fully compatible rst overview, but is sufficient for textual changes.