Building and Editing the Documentation

Section author: Luke Frisken <l.frisken@gmail.com>

Table of Contents

Introduction

This project uses Sphinx with the Read The Docs Theme for building this set of documentation. A number of other tools are also used to automatically generate API documentation and UML Diagrams.

Another good overview of the technologies used here is available at Wiser Readthedocs

Building the Documentation

Pre-Requisites

Linux

following packages need to be installed:

  • lxml2-dev
  • graphviz
  • java
  • pandoc

Windows

WARNING!

Windows build is currently unsupported/experimental as of the latest changes, it was not working on the team member’s computer who had windows, and I do not have time to install a windows VM to fix it myself. - Luke Frisken

Following the installation section labelled “All” found below is the general guideline for the Windows installation, however there are a few considerations that need to be made.

  • Install Pandoc. Link
  • The lxml package must be installed manually before installing javasphinx, find the corresponding lxml version by matching the python3 version you have installed. Link

All

A number of things need to be installed on your computer before attempting to build the documentation.

Firstly Python, preferably Python 3 needs to be installed. Python can be obtained from: https://www.python.org/downloads/

The following Python modules also need to be installed:

The required python modules can all be installed with the following command run in the documentation folder:

$ pip install -r requirements.txt

Included in the git repo for your convenience, but also by definition, required are:

  • PlantUML (plantuml.jar) - For rendering UML diagrams
  • PlantUML Dependency - For generating PlantUML class dependency diagrams from java source code

Build

To build the documentation, run this command from the documentation folder:

$ make html

The documentation can then be found in the _build/html folder.

Autobuild

If you’d like documentation to automatically build upon changes to its source files, and to show in the browser, there is a fantastic python module called sphinx-autobuild. It can be installed using:

$ pip install sphinx-autobuild

You can then run:

$ make livehtml

which will open up the documentation in a live browser view.

See the python package index page for more information on how to use.

Clean

Occasionally the cache gets a little messed up and items can go missing from the index or toolbar. In this case you can clean the build to allow the documenation to be rebuilt from scratch with this command:

$ make clean

Deploy

To deploy the documentation, I’m using this method to publish docs to a gh-pages branch on github: https://gist.github.com/ramnathv/2227408

RestructuredText Support

Sphinx’s default documenation markup is called reStructuredText. A good overview of the syntax is available here and here. A more formal specification of the syntax is available here

Markdown Support

This project’s documentation supports the Sphinx default markup language of reStructuredText with .rst files, but it also supports Markdown with .md files. The preferred language for use in this documentation is Markdown, although reStructuredText statements can be inserted into the Markdown using a special method when neccessary.

Taken from John Gruber’s website:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext, and EtText — the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like emphasis. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown Syntax

A good overview of the syntax of markdown is available here, and more succinctly here

A more formal specification of its syntax has now been provided called CommonMark, which can be found here

Markdown Tools

Markdown has fairly widespread support among the popular text editors. If you’re using sublime a couple of tools can make your life easier:

Extra Markdown Features

The AutoStructify module for ReCommonMark is in use for this documentation to allow extra features in markdown for use in Sphinx documentation. These features include:

UML

We are using PlantUML for our UML diagramming. Diagrams are defined using a simple language (see PlantUML Language Reference Guide). Diagrams are inserted into rst/markdown files in Sphinx as svg images.

The command to generate an svg image is:

$ plantuml -tsvg diagram.puml

The reStructuredText syntax for inserting this image as a figure is:

.. figure:: diagram.svg
    :width: 100 %
    :align: center

    Caption for diagram

Dependency Diagram Generation

You can use PlantUML Dependency like this to generate a dependency diagram for source code. The contents can then be copied into a markdown file:

java -jar ./tools/plantuml-dependency-cli-1.4.0-jar-with-dependencies.jar -b . -i **/*.java -o atc_simulator.puml -dp ^.*com[.]atc[.]simulator.*$

An example of the diagram generated with this command can be found in Libgdx ATC Simulator section of the documentation.