Developer and Internals » Documentation Guide

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

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
    • curl https://bootstrap.pypa.io/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
  4. Go into the documentation folder and build
    • cd m.css/documentation/
    • python3.6 doxygen.py <path_to_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 /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