docu: a few tweaks towards better Doxygen usage

mainly subpaging the few existing docu pages

Author: torbjoernk

Doxyfile

@@ -279,7 +279,12 @@ CPP_CLI_SUPPORT        = NO
 
 SIP_SUPPORT            = NO
 
-# For Microsoft's IDL there are propget and propput attributes to indicate getter and setter methods for a property. Setting this option to YES (the default) will make doxygen replace the get and set methods by a property in the documentation. This will only work if the methods are indeed getting or setting a simple type. If this is not the case, or you want to show the methods anyway, you should set this option to NO.
+# For Microsoft's IDL there are propget and propput attributes to indicate getter
+# and setter methods for a property. Setting this option to YES (the default) will
+# make doxygen replace the get and set methods by a property in the documentation.
+# This will only work if the methods are indeed getting or setting a simple type.
+# If this is not the case, or you want to show the methods anyway, you should set
+# this option to NO.
 
 IDL_PROPERTY_SUPPORT   = YES
 

README.md

@@ -20,7 +20,13 @@ XXX
 Documentation
 -------------
 
-Doxygen generated documentation can be found [on the PinT server][documentation].
+Doxygen generated documentation can be found [on the PinT server][documentation].  
+Currently, it features the following content:
+
+* \subpage #page_building_installing
+* \subpage #page_examples
+* \subpage #page_contributing
+* \subpage #page_style_guide
 
 
 Build status

doc/source/contributing.md

@@ -1,4 +1,4 @@
-# Contributing
+# Contributing                                                                  {#page_contributing}
 
 ## Branching and Tagging Model
 

doc/source/examples.md

@@ -0,0 +1,5 @@
+# Examples                                                                          {#page_examples}
+
+## Simple Advection Diffusion
+
+See \subpage page_examples_advection_diffusion.

doc/source/installing.md

@@ -1,4 +1,4 @@
-# Building and Installing
+# Building and Installing                                                {#page_building_installing}
 
 ## Prerequesites
 

doc/source/style_guide.md

@@ -1,4 +1,4 @@
-# Style Guide
+# Style Guide                                                                    {#page_style_guide}
 
 ## Naming Convention
 

examples/advection_diffusion/README.md

@@ -1,20 +1,16 @@
-Advection/diffusion
-===================
+# Advection / Diffusion                                         {#page_examples_advection_diffusion}
 
-This directory contains several implementations of an
-advection/diffusion solver using the PFASST framework.
+This directory contains several implementations of an advection/diffusion solver using the PFASST 
+framework.
 
-All of the solvers use the SDC sweeper defined in
-`advection_diffusion_sweeper.hpp`, and the FFT routines in `fft.hpp`.
+All of the solvers use the SDC sweeper defined in `advection_diffusion_sweeper.hpp`, and the FFT 
+routines in `fft.hpp`.
 
 The implementations are, in order of complexity:
 
-* `vanilla_sdc.cpp` - basic example that uses an encapsulated IMEX
-  sweeper.
+* `vanilla_sdc.cpp` - basic example that uses an encapsulated IMEX sweeper.
 
-* `serial_mlsdc.cpp` - basic multi-level version that uses polynomial
-  interpolation in time and spectral interpolation in space, as
-  defined in `specrtal_transfer_1d.hpp`.
+* `serial_mlsdc.cpp` - basic multi-level version that uses polynomial interpolation in time and 
+  spectral interpolation in space, as defined in `specrtal_transfer_1d.hpp`.
 
-* `serial_mlsdc_autobuild.cpp` - same as above, but uses the "auto
-  build" feature to shorten `main`.
+* `serial_mlsdc_autobuild.cpp` - same as above, but uses the "auto build" feature to shorten `main`.