98 lines
3.9 KiB
Plaintext
98 lines
3.9 KiB
Plaintext
/**
|
|
|
|
|
|
@page dev-docs Documentation Guide
|
|
|
|
|
|
@section developers-pdfmanual 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](https://stackoverflow.com/a/50986638/7718197) 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`
|
|
|
|
|
|
|
|
@section developers-addpage Adding a Website Page
|
|
|
|
1. Add a `doc/pagename.dox` file, copy up-to-date license header.
|
|
2. Add a @c \@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 @c \@subpage in its parent page
|
|
5. Leverage @c \@section and @c \@subsection to separate the page
|
|
|
|
|
|
|
|
@section latex 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 [])
|
|
|
|
|
|
|
|
@section developers-building 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
|
|
- bibtex executable in search path
|
|
- perl executable in search path
|
|
- 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>`
|
|
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
|
|
|
|
|
|
@section developers-theme Custom m.css Theme
|
|
|
|
1. This is based on the [m.css docs](https://mcss.mosra.cz/css/themes/#make-your-own) 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
|
|
|
|
|
|
@section developers-figures Creating Figures
|
|
|
|
- One of the editors we use is [IPE](http://ipe.otfried.org/) 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`
|
|
|
|
|
|
*/ |