[Boost-docs] LaTeX formulas in Doxygen comments

Subject: [Boost-docs] LaTeX formulas in Doxygen comments
From: Eric Niebler (eric_at_[hidden])
Date: 2008-01-08 18:20:00

I figured out a (slightly hackish) way to have LeTeX formulas in Doxygen 
comments automatically generate .png files that are properly linked to 
from the generated HTML. I thought I'd share. You'll need doxygen, 
latex, dvips and gs (ghostscript) installed, (and doxygen configured 
with bbv2 and the rest in your path).

Imagine you have a Doxygen comment in your code like:

     /**
         @brief Estimation of the absolute and relative tail variate
                means (for both left and right tails)

         \f[
             \widehat{ATM}_{n,\alpha}^{\mathrm{right}}(X, j) =
                 \frac{1}{\lceil n(1-\alpha) \rceil}
                 \sum_{i=\lceil \alpha n \rceil}^n \xi_{j,i}
         \f]
     */
     struct tail_variate_means_impl { ... }

Doxygen will automatically emit a .png file for this, but only if you're 
generating HTML. By default, doxygen+bbv2 emits XML, but you can also 
emit HTML like this:

     # Generate HTML instead of XML
     # (The .html suffix is significant)
     doxygen statsdoc.html : the souces ... ;

This will generate a lot of HTML and some .png files for your equations. 
The png files will be called form_0.png, form_1.png, etc. They need to 
be copied into your images/ directory, or preferably into a subdirectory 
to avoid conflicts. Here's some bbv2 magic Rene helped me write:

     if [ os.name ] = NT
     {
         CP = copy /y ;
         FROM = \\..\\..\\html\\statsdoc\\*.png ;
         TO = .\\html\\images\\accumulators ;
     }
     else
     {
         CP = cp ;
         FROM = /../../html/statsdoc/*.png ;
         TO = ./html/images/accumulators ;
     }

     actions copy-latex-pngs
     {
         mkdir $(TO)
         $(CP) $(<:D)$(FROM) $(TO) && echo "Stamped" > "$(<)"
     }

     # This causes the png files built above to be copied
     # into the html/images/accumulators directory.
     make statsdoclatex.tag
         : statsdoc.html
         : @copy-latex-pngs
         ;

Now we have built pngs and put them someplace sensible. Now you have to 
invoke doxygen on the sources again to generate XML and tell it where to 
find the png files.

     doxygen statsdoc
       : the sources ...
       : <xsl:param>boost.doxygen.formuladir=images/accumulators/
         <dependency>statsdoclatex.tag
       ;

The boost.doxygen.formuladir is relative to the html/ directory. The 
<dependency> is so that the png files are rebuilt when necessary. And 
that's it! What could be simpler? <cough>

Many thanks to Rene for helping out and fixing a bug in doxygen.jam for me!

-- 
Eric Niebler
Boost Consulting
www.boost-consulting.com