Building this Documentation

Components

In the following, we briefly explain how to build documentation for anyone working in the Robot Intelligence Lab, and especially for those working on projects with Robot DE NIRO. Here, first, are our primary tools:

  • reStructuredText: All documentation files (i.e. the actual text files you will edit) are written as reStructuredText files with .rst file suffixes. reStructuredText is a simple markup language like LaTeX or HTML. It is even closer to normal written text than these, but this comes at the cost of some flexibility.
  • Sphinx: This is a compiler for rendering reStructuredText source files into elegant HTML pages, LaTeX-style PDFs, and more.
  • Read the Docs: A documentation template from Sphinx you can configure or adjust.
  • GitLab.com: A git-based website where we store and update the documentation. We can build the documentation automatically using GitLab’s pipelines to produce HTML files (these are hosted separately; more details in Working with the Documentation).

Getting Started

To get started, we highly recommend watching the first part of this tutorial for an overview. After that, follow these steps:

  1. Create a GitLab page by forking the example Sphinx project. We recommend doing this from a separate GitLab repository.
  2. Since we are forking this for our own use, and we will not be contributing back to the upstream project, we can remove the forking relationship. To do this, go to your newly forked repository. On the left bar, select Settings, then click to Expand Advanced Settings, and finally click the red button to Remove Fork Relationship. You will see an intimidating form, but press on by confirming the removal.
  3. In your newly independent repository, edit your .gitlab-ci.yml file. Add - pip install sphinx_rtd_theme as part of the script tag just after - pip install sphinx. The .yml file specifies what what will execute when the pipeline is triggered. Thus, this new line ensures that our preferred theme gets installed.
  4. Configure the conf.py file. In particular, set the html_theme equal to 'sphinx_rtd_theme'

That’s all for setting it up! To understand how you can edit the documentation, go to Working with the Documentation.

Credits

What is a research project without acknowledging the work of others? With regards to the documentation, we want to thank Benedict Greenberg et. al for introducing us to using Sphinx and Read the Docs. We used their work to produce the documentation you see before you.