This repository contains common utilities for different projects developed at GRAB lab. They are organized in library form, divided by topic:
- libnumeric: numeric library with minimal matrix class implementation and related tools, and few numerical solvers;
- libgeom: geometric library with rotation parametrization and derivatives, and quaternion minimal class implementation;
- libcdpr: library including kinematics, dynamics and other utilities related to a generic Cable-Driven Parallel Robot;
- libgrabec: library providing basic functionalities to setup an EtherCAT communication system;
- libgrabrt: library providing basic functionalities to setup a Real-Time thread, provided that you are working on a RT Unix machine.
To auto-generate an user-friendly documentation straight out of the source code, we make use of well-known software tool Doxygen. On the official website you can find all the details about how to use it, install it and build it. While we provide here a short tutorial on how to integrate it in our Qt-based framework, we leave to the user the task of reading the manual on the format to be employed when writing documentation within the code. Bear in mind that in this project we opted for JavaDoc style, so please comply with it.
First of all, you need to download the tool itself (you can skip this step if it is already installed in your machine). To do so, open a terminal and type the following command:
sudo apt-get install doxygen doxygen-gui
That's it. Now Doxygen is installed and ready to be used.
Next, you need to setup a Doxyfile, which yields all the instructions to generate the documentation out of your code. Instead of compiling this file yourself, Doxygen provides a nice wizard to walk you throug all the necessary step: doxywizard.
To start it, just type doxywizard
in a terminal and a small GUI will appear.
Feel free to adapt the settings to your specific need, but the minimal setup for this library should include the following:
- In
Step 1
, select $MYPROJECTPATH, where $MYPROJECTPATH is the absolute path to your project root directory. - In
Step 2
, in the tabWizard
, selectProject
underTopics
and do the following:- Fill project information, such as
Project name
, as desired - Select $MYPROJECTPATH as
Source code directory
and tickScan recursively
option below - Select $MYPROJECTPATH/doc as
Destination directory
(make directory if it does not exist yet)
- Fill project information, such as
- In
Step 2
, in the tabWizard
, selectOutput
underTopics
and untick LaTeX option unless desired. - In
Step 2
, in the tabExpert
, selectHTML
underTopics
and tickUSE_MATHJAX
option to display mathematical formulas. - In
Step 2
, in the tabExpert
, selectInput
underTopics
, go toFILE_PATTERNS
and remove all extensions except *.c, *.cc, *.cpp, *.c++, *.h, *.hh, *.hpp, *.h++ by selecting them and clicking the minus button. Look below forEXCLUDE_PATTERNS
and add tests and doc by clicking the plus button. In theEXCLUDE
list right above you should also add any build folder which is inside the source code directory. Finally add the following words to theEXCLUDE_SYMBOLS
list:- STATE_DEFINE
- GUARD_DEFINE
- ENTRY_DEFINE
- EXIT_DEFINE
- To test your configuration, in
Step 2
, go to tabRun
and clickRun doxygen
button. In the integrated console you will see your documentation building up. When it is done, click onShow HTML output
and you will be prompted to a web page on your favourite browser, which you can navigate on. - Close the window. You will be asked to save the Doxyfile in the project directory. Do it as it suggests and you are done! Obviously, you can edit your configuration file with your favourite text editor in a later stage.
Assuming the code you want to document already belongs to a Qt project, open it with QtCreator and go to Projects tab. In the Build Settings, under the Build Steps section, click on Add Build Step
button and select Custom Process Step
.
In the Command
field type doxygen
, while in the Arguments
field you need to write the absolute path to the Doxyfile we just created, i.e. $MYPROJECTPATH/Doxyfile.
That's it! On your next build, Doxygen will parse all the files present in the project, look for documented lines within the code and generate an html
file with all the information found nicely arranged.
The main file you want to open is index.html
, which you will find in the specified doc folder.
Note that Doxygen may generates a lots of warning, especially the first times you use it, because your code is probably not yet compliant with all the formatting rules. These warnings do not affect the performance or outcome of your application, but can hide serious ones generated because of specific user-specific errors, unrelated to documentation. Our suggestion is to lose some time at the beginning to solve them one-by-one, and add compliant comments while developing new code right away as you move forward. It is a good practise which makes life easier for you and especially for your future and present colleagues! :)