Contributing to the Documentation¶

One of the best ways that you can help is by improving this documentation.

The documentation source files are stored in Github. The content is written in plain-text files (file-extension .rst) using reStructuredText markup, and is compiled into HTML using the Sphinx Documentation Generator.

Analyzer API reference documentation is automatically imported from doc strings in the source code header files (DOxygen is used to extract the strings into XML, which are then imported by Sphinx using the Breathe plugin).

Here we explain how to use the documentation system and submit your changes.

Submitting changes¶

The process and requirements for submitting changes to the documentation are the same as when contributing to the source code.

As when submitting source code you should create a sensibly name branch in the main dronekit/dronekit-la/ repository and contribute changes back to the project master branch using pull requests. The changes should be tested locally (by building the docs) before being submitted.

See Contributing to DroneKit-LA for more information.

Building the docs¶

The easy way (Vagrant)¶

We’ve made it very easy to get started by providing a “no configuration” Vagrant setup that you can use to build both the tool and documentation.

Using Vagrant you can work with source files on your host machine via a familiar git client and text editor, and then invoke Sphinx in the Vagrant VM to compile the source to HTML.

For more information see Building the Documentation in Vagrant.

Building docs on native OS¶

You can also build the documentation directly on your computer.

To do this you will need:

Sphinx - Generates the documentation from .rst source files.

Download for your platform from here.
sphinx-3dr-theme - A custom theme for Sphinx.

This can be installed using PIP:
```
pip install sphinx-3dr-theme
```
Doxygen - Generates XML files for in-source documentation strings (must be run every time your source code changes).

Download for your platform from here.
Breathe - Plugin to import API definitions from XML into Sphinx documentation.

This can be installed from the PyPi package repository as shown (the project is configured to use this plugin if it is present).
```
pip install breathe
```

After installing the toolchain, first run Doxygen from the root of your clone of dronekit-la and then navigate to /docs to build the documentation:

cd /dronekit-la
doxygen doxygen/doxygen.conf
cd /docs
make clean
make html

Tracking todo items¶

Generally it is best to track activities using Github issues. In some cases it can be useful also to include “todo” notes in the documentation source. You can do this using the todo directive, and the output will only be rendered if you build with the todo_include_todos flag enabled.

Add todo notes just like a “note”, “warning”, “tip” etc.
```
.. todo::

    This is todo text
```
Build using the following invocation to display todo messages.
```
make html SPHINXOPTS="-D todo_include_todos=1"
```
Use the todolist directive to list all todo’s in the build. This page has such a link below (so if this is a todo-enabled build you will see them).

Style guide¶

Tip

This guide is evolving. The most important guidance we can give is to copy the existing style of reference, guide and example material!

Use US English for spelling.
Use emphasis sparingly (italic, bold, underline).
Use Sphinx semantic markup to mark up types of text (key-presses, file names etc.)
Use double backticks (``) around inline code items.