Citations with Doxygen

Doxygen allows citations via the \cite command. For this to work you need BibTeX bib files. The .bib files can be created in a text editor or, optionally, exported from Zotero.

This is described in Doxygen's documentation, but the description is quite terse. Let's go through it in detail.

This is how it hangs together:

You'll need Latex and BibTeX software. I use TexLive, which includes both. From now on I'll assume you're also using TeX Live.

Download and install the software:

Download Doxygen.
Download and install Perl. Don't be distracted by mention of licence fees, there's a free "community edition."
Download and install Tex Live.
Note
The Tex Live install is around 300 MB, but I found it incredibly slow to install. It took well over an hour on a Surface Pro 2. Once installed it just works.

Configure Doxygen

Start in a clean folder, with Doxygen on the path:

E:\test>where doxygen
c:\portable\Doxygen-1.8.13\doxygen.exe
 
E:\test>

Create a Doxygen configuration file

Enter doxygen -g to generate a configuration file. This will be named Doxyfile.

E:\test>doxygen -g
 
Configuration file 'Doxyfile' created.
 
Now edit the configuration file and enter
 
  doxygen Doxyfile
 
to generate the documentation for your project
 
E:\test>

Create a markdown file

Fire up a text editor and create index.md:

# Hello World {#mainpage}

Groovy in Action is an excellent book. \cite gina2e

Note how I've included a citation. For this to work Doxygen will need a BibTeX file.

Create a BibTeX file

Create a test BibTeX file, test.bib, with your favourite editor. I'll cover using Zotero for this later.

@book{ gina2e,
    author    = "Dierk König and Paul King",
    title     = "Groovy in Action, Second Edition",
    ISBN      = "9781935182443",
    year      = "2015",
    publisher = "Manning Publications Co.",
    address   = "New York"
}

You need to point Doxygen at the BibTeX file you just created. To do this open Doxyfile, in a text editor, and search for CITE_BIB_FILES, it's probably at line 100:

CITE_BIB_FILES         =

Add the BibTeX file name after the equals sign and save the file:

CITE_BIB_FILES         = test.bib

Note: Doxygen is expecting list of file names, separated by spaces. If you used a space in your BibTeX file name then surround the name with double quotes in the CITE_BIB_FILES line.

Enable Latex and / or HTML

By default Doxygen will generate HTML output, but not Latex. (Citations work in both output formats.)

Search for 'GENERATE_HTML':

#---------------------------------------------------------------------------
# Configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML          = YES

I tend to create both HTML and Latex, so I leave the GENERATE_HTML line as is, but I change the GENERATE_LATEX line to YES:

#---------------------------------------------------------------------------
# Configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX         = YES

Running Doxygen

This is the easy bit: just type in doxygen and hit enter. You'll see a screen of output ending with the line "finished..."

Doxygen has created two output folders, one for HTML and another for Latex, assuming you enabled both:

E:\test>dir/b
Doxyfile
index.md
html
latex
test.bib

E:\test>

HTML Output

Use a browser to open the html/index.html file. You should see something like this:

Note the "[1]" replacing the "\cite gina2e" you typed into the markdown file. Click this and you'll be taken to the bibliography:

Latex output

The latex folder contains everything you need for a latex document, including two make files; one for Window and another for Linux / OS X:

E:\test>cd latex

E:\test\latex>dir/b
Makefile
make.bat
doxygen.sty
refman.tex
index.tex
bibTmpFile_1.bib
citelist.tex

E:\test\latex>

Run the make file, that's appropriate for your OS, and refman.pdf will be created.

Note: Running the make file will cause hundreds of arcane messages to scroll past, at a frantic pace. This is normal.

The generated PDF works in exactly the same way as the HTML page.

There's a page with the content, with a hyperlinked "1" to take you to the bibliography.

At the end of the PDF you'll find the bibliography:

The next step is to use a BibTeX file exported from Zotero. I'll cover that tomorrow.

Interesting web pages

BibTeX Format Description – BibTeX.org
Doxygen CITE_BIB_FILES – Doxygen documentation
How do you make your CS lectures more interesting? – Computer Science Educators Stack Exchange

Interesting Tweets

Zotero can export to BibTeX. Then point Doxygen at the BibTeX bib files and tell it to create latex output. Use \cite in your markdown.

– Tweet via @terry_ebdon

Find me coding on GitHub, networking on LinkedIn, answering questions on Stack Exchange and hanging out on twitter.

Table of Contents