Ask The Oracle

...A Tech blog for Engineers, Software Devs, and Computer Geeks

How to Add Graphics in Doxygen PDF files

Written by BobW on April 15th, 2010

In a previous post, “Document Your Software the Easy Way with Doxygen”, I discussed how to use Doxygen to create documentation for you software project.  This post shows you how to add graphics to the PDFs generated by Doxygen.

The software can generate very nice graphics, including call graphs for functions showing which functions they call and which functions they are called by. Surprisingly, these only show up in the html generated documentation, not the PDF files. I searched online and could not find out how to get the graphics into the PDF files, so I created some code to fix this problem. I am going to show you some simple script files that allow you to include the graphics in the PDF version. I wrote the script using AWK, but you can easily rewrite it the scripting language of your choice.

Setup Steps

1) Make sure you have all of the required packages installed (I use MikTex (MikTex.org) for a LaTex installation, and GraphViz is also required).

2) Follow all installation instructions for generating standard pdfs . I am assuming that you have a complete setup now that can generate html output with graphics or pdf files without graphics. (I will show you how to include the graphics later.)

If this is not working for you refer to the Doxygen help files and the website documentation to get it working.

3) For the script files, I set up my directory structure as follows:

Src\
Docs\ html
Docs\ latex
Docs\ pdf

If you use a different structure, adjust the paths in the script files accordingly.

4) My .bat file calls an awk script to modify the refman.tex file. I used the gawk from Cygwin. You can install the awk version of your choice or rewrite it in another scripting language.

How it Works

The refman.tex file generated by Doxygen needs to be modified. You have to add one line to it. Find the line that starts:

\makeindex

and add this line after it
\graphicspath{{../html/}}

You could do this manually, but then you have to do it every time you generate a pdf, since refman.tex is rewritten each time.

This awk script does the modification:

makepdf.awk
——————————————————————————–

# This is an awk program that modifies the refman.txt file created by Doxygen
# to add the line needed to generate PDFs with graphics embedded.
#
# This file is called from makepdf.bat
#
{
if ($1 == "\\makeindex")                          # Find this line
{
print $0;
printf ("%s\n", "\\graphicspath{{../html/}}");  # Add this line after it
}
else
{
print $0
}
}

--------------------------------------------------------------——————

You can easily rewrite this in another scripting language if you prefer.

This script is called from the following simple .bat file, which also renames the refman.pdf file generated by Doxygen to the filename of your choice.

makepdf.bat
——————————————————————————–

REM This bat file converts a Doxygen latex file to PDF with embedded graphics
REM It calls a awk script that modifies refman.tex
REM It should be run after Doxygen is run.
REM
REM This .bat file should be in the Src directory!
REM
REM usage: makepdf <DocumentName>
where DocumentName is the you want for the PDF output file
REM
REM  this awk script modifies refman.tex
gawk -f makepdf.awk ..\Docs\latex\refman.tex >  ..\Docs\latex\temp.tex
copy /y  ..\Docs\latex\temp.tex ..\Docs\latex\refman.tex
del temp.txt
REM
REM call Make to generate the PDF file.
cd ..\Docs\latex
make pdf
REM
REM Create PDF directory if it does not exist
if not exist ..\pdf mkdir ..\pdf
REM
REM Rename refman.pdf to <YourFilenam>.pdf
copy refman.pdf  ..\%1.pdf
del refman.pdf
cd ..\..\Src

——————————————————————————–

How to Run It

1) Make sure that makepdf.awk and makepdf.bat are in the Src directory (or adjust the paths in these script files accordingly)

2) Run Doxygen normally (I run it from the doxywizard, however you can run it from the command line if you prefer)

3) When it finishes successfully, type:
makepdf  MyDocumentName

4) This will create a pdf named MyDocumentName.pdf (or whatever you called it) in your pdf directory. It will contain the same graphics as the html output. (If you want graphical call trees, make sure you select those options when you run Doxygen)

I don’t know why the ability to produce graphical PDFs was not included in Doxygen in the first place. Maybe it will included in a future release. However, this script will do it for you now.

You must be logged in to post a comment.