diff --git a/Doxyfile b/Doxyfile
index e0a66160e1..6f5786a824 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -892,7 +892,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = README.md
+USE_MDFILE_AS_MAINPAGE = ./README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
diff --git a/sw/airborne/math/README.md b/sw/airborne/math/README.md
index d318e77264..59ec0eb78d 100644
--- a/sw/airborne/math/README.md
+++ b/sw/airborne/math/README.md
@@ -1,12 +1,17 @@
-Math lib used in all airborne code of paparazzi
+# Math library
+
+Math lib used in all airborne code of paparazzi.
+
+See also the @ref math docs.
 
 HOWTO install a shared library to use in other projects
+-------------------------------------------------------
 
 1. Build library: in this folder, type
-  make shared_lib
+  `make shared_lib`
 
   the default build directory is var/build/math
-  to change it: BUILDDIR=<your_build_dir> make shared_lib
+  to change it: `BUILDDIR=<your_build_dir> make shared_lib`
 
 2. Install library: in this folder, type
   make install_shared_lib
@@ -17,17 +22,18 @@ HOWTO install a shared library to use in other projects
   /usr/local/lib/pkgconfig
   /usr/local/include/pprz
 
-  to change the install dir: PREFIX=<your_install_dir> make install_shared_lib
+  to change the install dir: `PREFIX=<your_install_dir> make install_shared_lib`
 
   note that the default install dir needs root privilege
 
 HOWTO use the shared library
+----------------------------
 
-1. with pkg-config --cflags --libs pprzmath
+1. with `pkg-config --cflags --libs pprzmath`
 
 2. by hand:
-  LIBS: -L<prefix>/lib -lpprzmath
-  CFLAGS: -I<prefix>/include/pprz
+- LIBS: `-L<prefix>/lib -lpprzmath`
+- CFLAGS: `-I<prefix>/include/pprz`
 
 
 "make clean" will only clean the build directory
diff --git a/sw/airborne/math/pprz_algebra.h b/sw/airborne/math/pprz_algebra.h
index efa2564f6d..88d7755955 100644
--- a/sw/airborne/math/pprz_algebra.h
+++ b/sw/airborne/math/pprz_algebra.h
@@ -23,6 +23,14 @@
  * @file pprz_algebra.h
  * @brief Paparazzi generic algebra macros.
  *
+ * @addtogroup math
+ * @{
+ * Paparazzi math functions.
+ * @addtogroup math_algebra Algebra functions
+ * @{
+ * Algebra functions and macros.
+ * @addtogroup math_algebra_generic Generic Algebra macros
+ * @{
  */
 
 #ifndef PPRZ_ALGEBRA_H
@@ -740,3 +748,6 @@ extern "C" {
 #endif
 
 #endif /* PPRZ_ALGEBRA_H */
+/** @}*/
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_algebra_double.h b/sw/airborne/math/pprz_algebra_double.h
index 98861041a1..d8091d8873 100644
--- a/sw/airborne/math/pprz_algebra_double.h
+++ b/sw/airborne/math/pprz_algebra_double.h
@@ -22,6 +22,10 @@
  * @file pprz_algebra_double.h
  * @brief Paparazzi double precision floating point algebra.
  *
+ * @addtogroup math_algebra
+ * @{
+ * @addtogroup math_algebra_double Double Algebra
+ * @{
  */
 
 #ifndef PPRZ_ALGEBRA_DOUBLE_H
@@ -193,3 +197,5 @@ static inline void double_rmat_of_eulers(struct DoubleRMat *rm, struct DoubleEul
 #endif
 
 #endif /* PPRZ_ALGEBRA_DOUBLE_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_algebra_float.h b/sw/airborne/math/pprz_algebra_float.h
index 0b619fb3d9..3e9b940357 100644
--- a/sw/airborne/math/pprz_algebra_float.h
+++ b/sw/airborne/math/pprz_algebra_float.h
@@ -22,6 +22,10 @@
  * @file pprz_algebra_float.h
  * @brief Paparazzi floating point algebra.
  *
+ * @addtogroup math_algebra
+ * @{
+ * @defgroup math_algebra_float Float Algebra
+ * @{
  */
 
 #ifndef PPRZ_ALGEBRA_FLOAT_H
@@ -699,3 +703,5 @@ static inline void float_mat_col(float *o, float **a, int m, int c)
 #endif
 
 #endif /* PPRZ_ALGEBRA_FLOAT_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_algebra_int.h b/sw/airborne/math/pprz_algebra_int.h
index 100dfc1053..810aa2c559 100644
--- a/sw/airborne/math/pprz_algebra_int.h
+++ b/sw/airborne/math/pprz_algebra_int.h
@@ -22,6 +22,10 @@
  * @file pprz_algebra_int.h
  * @brief Paparazzi fixed point algebra.
  *
+ * @addtogroup math_algebra
+ * @{
+ * @addtogroup math_algebra_int Fixed Point Algebra
+ * @{
  */
 
 #ifndef PPRZ_ALGEBRA_INT_H
@@ -594,3 +598,5 @@ extern void int32_eulers_dot_321_of_rates(struct Int32Eulers *ed, struct Int32Eu
 #endif
 
 #endif /* PPRZ_ALGEBRA_INT_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic.h b/sw/airborne/math/pprz_geodetic.h
index a0d4cae1c6..a7c40b7a83 100644
--- a/sw/airborne/math/pprz_geodetic.h
+++ b/sw/airborne/math/pprz_geodetic.h
@@ -22,7 +22,13 @@
  * @file pprz_geodetic.h
  * @brief Paparazzi generic macros for geodetic calculations.
  *
- *
+ * @addtogroup math
+ * @{
+ * @addtogroup math_geodetic Geodetic functions
+ * @{
+ * Geodetic calculation functions and macros.
+ * @addtogroup math_geodetic_generic Generic Geodetic macros.
+ * @{
  */
 
 #ifndef PPRZ_GEODETIC_H
@@ -94,3 +100,6 @@ extern "C" {
 #endif
 
 #endif /* PPRZ_GEODETIC_H */
+/** @}*/
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_double.h b/sw/airborne/math/pprz_geodetic_double.h
index f349958cbd..18c851dbad 100644
--- a/sw/airborne/math/pprz_geodetic_double.h
+++ b/sw/airborne/math/pprz_geodetic_double.h
@@ -22,7 +22,11 @@
  * @file pprz_geodetic_double.h
  * @brief Paparazzi double-precision floating point math for geodetic calculations.
  *
- *
+ * @addtogroup math_geodetic
+ * @{
+ * Double Geodetic functions and macros.
+ * @addtogroup math_geodetic_double Double Geodetic functions
+ * @{
  */
 
 #ifndef PPRZ_GEODETIC_DOUBLE_H
@@ -124,3 +128,5 @@ extern double gc_of_gd_lat_d(double gd_lat, double hmsl);
 #endif
 
 #endif /* PPRZ_GEODETIC_DOUBLE_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_float.h b/sw/airborne/math/pprz_geodetic_float.h
index 14d7a72142..e8315e5dd7 100644
--- a/sw/airborne/math/pprz_geodetic_float.h
+++ b/sw/airborne/math/pprz_geodetic_float.h
@@ -122,3 +122,5 @@ extern void ecef_of_ned_vect_f(struct EcefCoor_f *ecef, struct LtpDef_f *def, st
 #endif
 
 #endif /* PPRZ_GEODETIC_FLOAT_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_int.h b/sw/airborne/math/pprz_geodetic_int.h
index 03dfa301b0..e2c69d2719 100644
--- a/sw/airborne/math/pprz_geodetic_int.h
+++ b/sw/airborne/math/pprz_geodetic_int.h
@@ -22,7 +22,10 @@
  * @file pprz_geodetic_int.h
  * @brief Paparazzi fixed point math for geodetic calculations.
  *
- *
+ * @addtogroup math_geodetic
+ * @{
+ * @addtogroup math_geodetic_int Fixed Point Geodetic functions
+ * @{
  */
 
 #ifndef PPRZ_GEODETIC_INT_H
@@ -240,3 +243,5 @@ extern void ecef_of_ned_vect_i(struct EcefCoor_i *ecef, struct LtpDef_i *def, st
 #endif
 
 #endif /* PPRZ_GEODETIC_INT_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_utm.h b/sw/airborne/math/pprz_geodetic_utm.h
index a3b5616ecc..18fd8a27ed 100644
--- a/sw/airborne/math/pprz_geodetic_utm.h
+++ b/sw/airborne/math/pprz_geodetic_utm.h
@@ -21,6 +21,10 @@
 /**
  * @file pprz_geodetic_utm.h
  * @brief Constants UTM (Mercator) projections.
+ * @addtogroup math_geodetic
+ * @{
+ * @addtogroup math_geodetic_utm UTM (Mercator) projections
+ * @{
  */
 
 #ifndef PPRZ_GEODETIC_UTM_H
@@ -61,3 +65,5 @@ static const float serie_coeff_proj_mercator_inverse[5] = {
 #endif
 
 #endif /* PPRZ_GEODETIC_UTM_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_wgs84.h b/sw/airborne/math/pprz_geodetic_wgs84.h
index 2659c4b079..9269ca4806 100644
--- a/sw/airborne/math/pprz_geodetic_wgs84.h
+++ b/sw/airborne/math/pprz_geodetic_wgs84.h
@@ -34,6 +34,10 @@
  *
  * rows are from -180 to +170 starting north +90 to south-90
  *
+ * @addtogroup math_geodetic
+ * @{
+ * @addtogroup math_geodetic_wgs84 WGS-84 Geoid
+ * @{
  */
 
 #ifndef PPRZ_GEODETIC_WGS84_H
@@ -92,3 +96,5 @@ static inline float wgs84_ellipsoid_to_geoid(float lat, float lon)
 #endif
 
 #endif /* PPRZ_GEODETIC_WGS84_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_geodetic_wmm2010.h b/sw/airborne/math/pprz_geodetic_wmm2010.h
index 89493612cd..fb8da26ad9 100644
--- a/sw/airborne/math/pprz_geodetic_wmm2010.h
+++ b/sw/airborne/math/pprz_geodetic_wmm2010.h
@@ -23,6 +23,11 @@
  * @brief WMM2010 Geomagnetic field model.
  *
  * Based on the WMM2010 model (http://www.ngdc.noaa.gov/geomag/models.shtml)
+ *
+ * @addtogroup math_geodetic
+ * @{
+ * @addtogroup math_geodetic_wmm Geomagnetic field model
+ * @{
  */
 
 #ifndef WMM2010_H
@@ -72,3 +77,5 @@ int16_t mag_calc(int16_t igdgc, double flat, double flon, double elev, int16_t n
 #endif
 
 #endif /* WMM2010_H */
+/** @}*/
+/** @}*/
diff --git a/sw/airborne/math/pprz_isa.h b/sw/airborne/math/pprz_isa.h
index 3d2085dcb9..a79ab1c301 100644
--- a/sw/airborne/math/pprz_isa.h
+++ b/sw/airborne/math/pprz_isa.h
@@ -29,6 +29,10 @@
  * http://en.wikipedia.org/wiki/Atmospheric_pressure
  * http://en.wikipedia.org/wiki/International_Standard_Atmosphere
  *
+ * @addtogroup math
+ * @{
+ * @addtogroup math_isa International Standard Atmosphere utilities
+ * @{
  */
 
 #ifndef PPRZ_ISA_H
@@ -166,3 +170,5 @@ static inline float pprz_isa_ref_pressure_of_height_full(float pressure, float h
 #endif
 
 #endif /* PPRZ_ISA_H */
+/** @}*/
+/** @}*/