Documentation Guide

This page is mostly intended for my own reference, as I found myself repeatedly looking up guides of a narrow subset of reStructuredText.

Markup Constructs

Structured content can be formatted with a directive. For example,

  • Comment

    .. This is a comment (not rendered in the output).

  • Headings (on way to do it)

    Heading 1
=========

Heading 2
---------

Heading 3
*********

  • Unordered lists

    + Item 1
+ Item 2
+ Item 3

    or just like Markdown,

    - Item 1
- Item 2
- Item 3

  • Message boxes (warning)

    .. warning::

   Warning: This is a warning message.

    which gets rendered into

    Warning

    Warning: This is a warning message.

  • Message boxes (note)

    .. note::

   Note: This is an important message.

    which gets rendered into

    Note

    Note: This is an important message.

Build the Documentation

Use the Makefile to build:

# Build the web version
$ make html

# Build the pdf version
$ make pdflatex

# Report documentation coverage
$ make coverage