Developer's Diary
Daily software development, with Terry Ebdon
Doxygen Citations

Friday 7th July, 2017

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:

  1. Download Doxygen.
  2. Download and install Perl. Don't be distracted by mention of licence fees, there's a free "community edition."
  3. 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:

2017-06-07_html_with_citations.png

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

2017-06-07_html_bibliography.png

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.

2017-06-07_latex_with_citations.png

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

2017-06-07_latex_bibliography.png

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

Interesting web pages

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


6th July 👈 Top of page 👉 8th July © 2017 Terry Ebdon

Find me on coding on BitBucket, networking on LinkedIn and hanging out on twitter.