documentation.rst

Documentation

This tutorial will teach you how to build the documentation locally and contribute to its development.

Introduction

These tutorials are written in rst, an easy-to-understand plaintext markup language. It is then build by Sphinx using the rosdoc_lite package. You can either build the documentation locally when following the tutorials or deploy it to GitHub pages with the help of Travis.

Building locally

Follow these steps to be able to build the documentation locally.

Clone the repository

Add the following entry to your .rosinstall file (recommended):

- git:
    local-name: march_tutorials
    uri: https://github.com/project-march/tutorials

And use wstool to update your workspace:

cd ~/march_ws
wstool update -t src

Or clone the repository manually in your source directory:

cd ~/march_ws/src
git clone https://github.com/project-march/tutorials march_tutorials

Note

The local repository should be called march_tutorials instead of the repository name tutorials to ensure we can uniquely access the launchfiles.

Install rosdoc_lite and Sphinx

We use the package rosdoc_lite to generate the documentation with Sphinx

sudo apt-get install ros-melodic-rosdoc-lite

Install Gem and html-proofer

Gem is a package manager for Ruby, we will use it to install html-proofer. html-proofer is a tool that can validate your generated html for mistakes like broken links or missing images.

sudo apt-get update
sudo apt install ruby-full

# Check if ruby and gem got installed correctly
ruby --version
gem --version

sudo gem update --system
sudo gem install html-proofer

Install Additional dependencies

Pygit is used so we can tell Sphinx what branch we are on. That way links to GitHub files can be verified against the proper branch. This prevents html-proofer from not being able to find newly added files on develop, as it checks against the current branch. Furthermore, we use the sphinx-rtd-theme for the theme of the pages. You can install both packages from the Ubuntu repositories:

sudo apt install python-pygit2 python-sphinx-rtd-theme

Generate the html

Simply run the :rootdir:`build_locally <build_locally.sh>` script to generate the docs and automatically open them in your browser.

cd ~/march_ws/src/march_tutorials
./build_locally.sh

Warning

If you already have sphinx installed, you might get the following error:

Traceback (most recent call last):
  File "/home/march/.local/bin/sphinx-build", line 7, in <module>
    from sphinx.cmd.build import main
  File "/home/march/.local/lib/python2.7/site-packages/sphinx/cmd/build.py", line 39
    file=stderr)
        ^
SyntaxError: invalid syntax
stdout:

Fix it by uninstalling sphinx

pip uninstall sphinx

Warning

You might get the following error if sphinx is installed using pip3:

Exception occurred:
  File "<frozen importlib._bootstrap>", line 222, in _call_with_frames_removed
  File "/home/olav/march_ws/src/march_tutorials/_scripts/tutorialformatter.py", line 121
    print 'tutorialformatter.py error: sub-tutorial %s not found.' % sub_name
                                                                 ^
SyntaxError: Missing parentheses in call to 'print'

You can fix this by uninstalling python3 sphinx:

pip3 uninstall sphinx

Note

If you have added new files but not pushed to GitHub yet, html-proofer will probably complain about invalid links. Push your files and build locally again to solve this problem.

sphinx-autobuild

sphinx-autobuild is a tool that watches your doc files and live updates your changes.

You can install it with pip:

pip install --user sphinx-autobuild

Start the auto build:

sphinx-autobuild . build/html

When you go to localhost:8000 it should open the documentation and live refresh when a file is changed and saved to disk.

Deploy with Travis

We make use of the Travis deploy feature to deploy our generated documentation to GitHub pages. Please check the :rootdir:`.travis.yml of this repository <.travis.yml>` for the details.

Add a new tutorial

Adding a new tutorial is as simple as creating a new .rst file. To make sure it shows up in the Table of Contents, add it to the :rootdir:`index.rst <index.rst>` under a .. toctree:: directive

Tip

If you are creating a new package description, make sure to base it off the :codedir:`package template <march_packages/template.rst>`