Documentation Guide

Building the Latex PDF Reference Manual

1. You will need to install doxygen and texlive with all packages
   • sudo apt-get update
   • sudo apt-get install doxygen texlive-full
   • You will likely need new version of doxygen 1.9.4 to fix ghostscript errors
2. Go into the project folder and generate latex files
   • cd open_vins/
   • doxygen
   • This should run, and will stop if there are any latex errors
   • On my Ubuntu 20.04 this installs version "2019.20200218"
3. Generate a PDF from the latex files
   • cd doxgen_generated/latex/
   • make
   • File should be called refman.pdf

Adding a Website Page

1. Add a doc/pagename.dox file, copy up-to-date license header.
2. Add a @page definition and title to your page
3. If the page is top-level, list it in doc/00-page-order.dox to ensure it gets listed at a proper place
4. If the page is not top-level, list it using @subpage in its parent page
5. Leverage @section and @subsection to separate the page

Math / Latex Equations

• More details on how to format your documentation can be found here:
  • http://www.doxygen.nl/manual/formulas.html
  • https://mcss.mosra.cz/css/components/#math
  • https://mcss.mosra.cz/css/components/
• Use the inline commands for latex \f $ <formula_here> \f $ (no space between f and $)
• Use block to have equation centered on page \f [ <big_formula_here> \f ] (no space between f and [])

Building the Documentation Site

1. Clone the m.css repository which has scripts to build
   • Ensure that it is not in the same folder as your open_vins
   • git clone https://github.com/mosra/m.css
   • This repository contains the script that will generate our documentation
2. You will need to install python3.6
   • sudo add-apt-repository ppa:deadsnakes/ppa
   • sudo apt-get update
   • sudo apt-get install python3.6 python3.6-distutils
   • curl https://bootstrap.pypa.io/pip/3.6/get-pip.py | sudo python3.6
   • sudo -H pip3.6 install jinja2 Pygments
   • sudo apt install texlive-base texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended
3. To use the bibtex citing you need to have
   • bibtex and perl executable in search path
   • These should be installed through the texlive installation
   • http://www.doxygen.nl/manual/commands.html#cmdcite
4. Go into the documentation folder and build
   • cd m.css/documentation/
   • python3.6 doxygen.py <path_to_Doxyfile-mcss>
   • python3.6 doxygen.py ~/catkin_ws/src/open_vins/Doxyfile-mcss
5. If you run into errors, ensure your python path is set to use the 3.6 libraries
   • export PYTHONPATH=/usr/local/lib/python3.6/dist-packages/
6. You might need to comment out the enable_async=True flag in the doxygen.py file
7. This should then build the documentation website
8. Open the html page ~/catkin_ws/src/open_vins/doxgen_generated/html/index.html to view documentation

Custom m.css Theme

1. This is based on the m.css docs for custom theme
2. Files needed are in open_vins/docs/mcss_theme/
3. Copy the following files into the m.css/css/ folder
   • m-theme-udel.css
   • pygments-tango.css
   • m-udel.css
4. Most settings are in the m-theme-udel.css file
5. To generate / compile the edited theme do:
   • python3.6 postprocess.py m-udel.css m-documentation.css -o m-udel+documentation.compiled.css
   • Copy this generated file into open_vins/docs/css/
   • Regenerate the website and it should change the theme

Creating Figures

• One of the editors we use is IPE which is avalible of different platforms
• We use the ubuntu 16.04 version 7.1.10
• Create your figure in IPE then save it to disk (i.e. should have a file.ipe)
• Use the command line utility iperender to convert into a svg
• iperender -svg -transparent file.ipe file.svg