Building and Editing the Documentation¶
Section author: Luke Frisken <l.frisken@gmail.com>
Table of Contents
- Project Documentation
- Introduction
- Building the Documentation
- RestructuredText Support
- Markdown Support
- UML
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¶
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.
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:
- sphinx_rtd_theme - A theme for sphinx
- recommonmark - A module required for parsing markdown files
- javasphinx - A module required for generating java documentation from java files
- sphinxcontrib-plantuml - A module required for displaying PlantUML diagrams in documetation
- pygments-markdown-lexer - A module required for using Pygments to give syntax highlighting to markdown documents
- nbsphinx - A module required to render jupyter notebooks
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:
- Markdown Extended Support for Sublime - better syntax highlighting
- Monakai Extended Theme - needed for above to take effect
- Omni Markup Previewer - live markdown preview in browser
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:
- toctree support
- References to other documents
- Url resolving for references to files in the git repository - example here
- Code blocks with syntax highlighting - see here for more details on the syntax and supported languages. List of languages and their names here
- Latex math formulas
- Embedded reStructuredText - very useful for sphinx rst commands
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.