[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)

             \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}
     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 ;
         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/

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

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:40 UTC