How to Write the Wiki

The goal of this page is to document how this wiki is written, with the goal of helping future users document their code and maintain the current content.

The Documentation Framework

The backbone of this wiki is reStructuredText, which is simply plain text with a special markdown syntax. ReStructuredText is written to .rst source files, which are then compiled to produce .html files.

The “compiler” used is Sphinx (, a documentation generator widely used by the Python community but also useful for other software projects. Sphinx allows the user separate style work from documentation work, in a similar way that LaTeX documentation works. This wiki uses a style provided by Read the Docs (, again widely used by a number of software projects due to its beauty, flexibility and cross-compatibility with a number of vieweing devices.

Ultimately, the produced .html files can be hosted online and viewed under a web browser. This wiki is hosted under the Github Pages framework, which allows easy hosting of the .html files, an integrated backup solution and collaboration with git version control.

A top-level view of the documentation framework can be seen in the following figure:


Installing the Documentation Tools

The documentation using reStructuredText and Sphinx requires relatively few tools and these are very easy to install. At the moment, documentation support is only given to users with a Debian Linux distribution or with macOS. If you have any other OS, you can make use of a Virtual Machine which will allow you to use a different OS without partitioning your drive. Please refer to Vmware Workstation Player ( or Oracle VirtualBox ( for virtual machine solutions.

1. Install Python 2.7

Python 2.7 is necessary to run Sphinx. Please note that this may be already included in your system. You can install it using the following command:

// Linux
sudo apt-get install python

// Mac
sudo easy_install python // although Macs usually come with python built-in
2. Install Sphinx

You can install the Sphinx documentation generator using the following commands:

// Linux
sudo apt-get install python pip
pip install sphinx sphinx-autobuild

// Mac
sudo easy_install pip
python -mpip install matplotlib --user
pip install sphinx sphinx-autobuild --user
3. Install Graphviz

The Graphviz software is used for creating the diagrams in the documentation, it is installed using:

// Linux
sudo apt-get install graphviz

// Mac
sudo easy_install graphviz
4. Clone the source repository

This repository contains the .rst source files that make up the wiki. These are stored under the source branch within the tudat repository of Place the contents of this repository inside a source folder. This can be done with the command:

cd ... // path where you want the folder to be created
git clone -b source source
5. Clone the gh-pages repository

This repository contains the .html files that build the wiki website. These are stored under the gh-pages branch within the tudat repository of Place the contents of this repository inside a build/html folder, next to your source folder. This can be done with the command:

cd ... // path where you want the folder to be created
git clone -b gh-pages build/html
6. Create the make.bat and the Makefile files

These two files should be placed next to the folders. They allow to build the wiki from the terminal with few commands.

Contents of the make.bat:


pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
  set SPHINXBUILD=python -msphinx
set SOURCEDIR=source
set BUILDDIR=build
set SPHINXPROJ=TUDelftAstrodynamicsToolbox

if "%1" == "" goto help

if errorlevel 9009 (
  echo.The Sphinx module was not found. Make sure you have Sphinx installed,
  echo.then set the SPHINXBUILD environment variable to point to the full
  echo.path of the 'sphinx-build' executable. Alternatively you may add the
  echo.Sphinx directory to PATH.
  echo.If you don't have Sphinx installed, grab it from
  exit /b 1

goto end




Note that for macOS, the make.bat file is not necessary.

Contents of the Makefile:

# Minimal makefile for Sphinx documentation

# You can set these variables from the command line.
SPHINXBUILD   = python -msphinx
SPHINXPROJ    = TUDelftAstrodynamicsToolbox
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile


Make sure that Makefile does not have an extension. On macOS, for instance, if you use TextEdit to create the file, it is possible that the file is automatically saved as .txt (with hidden extension).

7. Compiling the wiki

To compile the wiki, navigate using the terminal to the folder containing the make.bat file and launch the following command:

make html

This will compile the .html files which you can view using your favorite web browser.

The overall files structure should look as follows:

| build
|     |
|     | html
|          |
|          | index.html
|          | ...
| source
|      |
|      |
|      | index.rst
|      | ...
| make.bat
| makefile

Updating Documentation

If changes are made to the documentation (wiki and/or doxygen) . These changes need to be pushed to the correct repository.


For the wiki the contents of root/build/html/ need to be pushed to


For the Doxygen the contents of tudatBundle/tudat/Tudat/Documentation/ need to be pushed to

Wiki Style Guide

As mentioned above, the wiki is built using .rst files that contain a special mark-up. This files are linked together using toctree commands, that link the source files together.

Linking .rst Files

The wiki source files are organized in different folders, where each folder contains an index.rst file that serves are the header of such folder. The source files should be organized in folder with meaningful names:

| index.rst
| installation
|            |
|            | index.rst
|            | downloadTudatBundle.rst
|            | downloadTudatBundle
|            |                   |
|            |                   | commandLine.rst
|            |                   | smartgitDeveloper.rst
|            |                   | smartgitUser.rst
|            | ...
| tutorials
|         |
|         | index.rst
|         | prerequiredKnowledge
|         |                    |
|         |                    | index.rst
|         |                    | ...
|         | ...
| developerGuide
|              | index.rst
|              | ...
| ...

The files are then linked together in a top-down fashion from the top index.rst file. Such linking is done by means of toctree commands, which are placed within the source files:

.. toctree::
   :maxdepth: 2
   :caption: Contents



  • .. toctree::
    Launches the toctree command. Here we see a special syntax widely used in reStructuredText which are used to launch special commands.
  • :maxdepth: 2
    Defines the maximum number of levels to show in the toctree. Note that the corresponding source pages will still be linked, even if not shown. This option becomes irrelevant if hidden is used.
  • :hidden:
    Hides the toctree entirely from the page.
  • :caption:
    Defines the name of the toctree. In the Tudat wiki, this is only used in the top-level toctree.
  • self, installation/index, …
    Define the location of the corresponding source files to be linked in the toctree.


Having an index.rst file in each folder is done simply due to convention. You could use a different file name as long as you refer to it properly in the toctree.

Indentation in reStructuredText

Once the wiki source files have been linked, it is time to start writing your text. While doing so, it is highly emphasized to nest all similar content among different categories and captions. To do so, you need to use the indentation system of reStructuredText, which consist on sequentially adding blocks of 3 whitespaces depending on the indentation level. For instance:

First level
   Bla bla bla starts after 3 whitespaces.

   Second level
      Bla bla bla starts after 6 whitespaces

      Third level
      Bla bla bla starts after 9 whitespaces

Where all text with an indentation of at least 3 whitespace belongs to the caption “First level”, all text with an indentation of at least 6 whitespace belongs to the caption “Second level” and all text with an indentation of at least 9 whitespace belongs to the caption “Third level”.


It is important to realize that the “3-whitespaces” rule is applicable to all commands within reStructuredText. In fact, many commands require to add all the relative content to such command with an indentation of 3 whitespaces for the command to actually work. For instance:

.. code-block:: cpp

   This text WILL be recognized within code-block.

.. code-block:: cpp

This text WILL NOT be recognized within code-block.

Use of Special Commands

One of the most powerful features of reStructuredText is the ability to use complex mark-up. It is required that you make use of it to ensure that the wiki stays pretty and clear. The best advice we can give you is to go through existing wiki pages and cross-check against the source code that generates them. You can do so by clicking on “View page source” on the top-right corner of the page.

The following commands are available within reStructuredText

  • .. warning::, .. note::, .. tip::

    These commands place coloured boxes which highlight particular content relevant to the current page. .. warning:: should be used for critical information will likely lead to issues if ignored. .. note:: should be used to extend the information beyond the regular paragraphs for further clarification, but is not critical for the end-user. .. tip:: should be used for non-critical information that can help the user in solve further problems than the one treated.

  • .. code-block:: cpp

    Sets a box with a monospaced box that contains C++ (cpp) marked-up code. You can use alternative designators such as reStructuredText (rst), MakeFile (makefile) or Windows Batch files (bat), among others.

  • **this text goes in bold**

    Makes the text enclosed by double multiplication signs bold.

  • *this text goes in italics*

    Makes the text enclosed by single multiplication signs italics.

  • :literal:``

    Introduces text in a red monospaced font. Should be used to refer to “software objects”, such as clickable buttons in GUIs, files, folders, variables, etc.

  • :class:``

    Introduces text in a black monospaced font. Should be used to refer to C++ classes. In Tudat, these are generally identified by variable names where each word is capitalized, such as in ExampleClass.

  • .. _exampleReferenceLink:

    Introduces a referable link, typically used at the start of sections. Similarly to cross-links used in LaTeX.

  • :ref:`exampleReferenceLink`

    Introduces an inline link to the page designated with .. _exampleReferenceLink:.

  • .. class:: ExampleClass

    Creates a special environment for class objects. If a :class:`ExampleClass` exists within the wiki, it will exist as a clickable object that redirects the user to the environment defined here.

  • use of semi-colon after a paragraph::

    Introduces a box of monospaced text without mark-up. Generally used to define file locations.

  • .. figure:: path/to/image.png

    Adds a figure at the same location in the text.


PDF figures are not supported by all web browsers. The standard figure format on the Tudat wiki is PNG.

Upcoming Improvements

The following issues on the github project page need to be resolved. Other improvements to the documentation are:

  • High priority.

  • Medium priority.

    • Update Qt project tree page to new layout occuring in latest Qt release.
    • Move gh-pages and source branch of tudat repo to seperate repo.
  • Low Priority.

    • Explain important functions in Basics/utilities.h
    • Classes which need to be defined:
      GroundStationState, PPNParameterSet, BasicSolidBodyTideGravityFieldVariations, ConstantObservationBias, ConstantRelativeObservationBias, JsonSimulationManager, MAssPropagationSettings, CustomStatePropagationSettings, MultiTypePropagationSettings, MultiArcPropagationSettings
    • Fix large literals which go beyond page margins such as in Defining estimation input.
    • Extensively refer to the Tudat libraries in the JSON interface List of Keys.
    • Update the definition of the observation bias/bias estimation.
    • Make the differences between Windows and *NIX instructions clear in <>_.