Running Doxygen

Doxygen is a nice tool, but using it comfortably is not very well explained in its documentation as this is supposed to be a tool used by people who have a little idea of what a console is. So the manual briefly says:
To generate the documentation you can now enter:

doxygen <config-file>

This assumes you have a console opened, in the right path. On a modern OS, it is much simpler to add an extension to the doxygen configuration file type (.dox seems of course appropriate, but its your choice), and to associate this extension to the considered program, so that a simple double click on the file will run doxygen, using this file as input.

With Windows, this association can be done easilly by selecting the .dox file, and selecting the "open with..." entry in the contextual menu. You can then navigate up to the doxygen/bin folder, and select doxygen.exe. I'm sure it is as simple on other OSes. However, this has some disadvantages, particularly on Windows. The default console behaviour that gets opened using the method described here gets closed when the program ends. So ?

Well, some times, things can go wrong. Either your code documentation is not correct, either there is a problem with your configuration file. In these cases, Doxygen outputs on standard error stream (stderr) a list of error messages that are very valuable. As the console closes, you lose all these error messages, not to mention that you can even not notice them. Moreover, even if you launch it from a previously opened console, doxygen is quite verbose on standard output (stdout), so important error messages get drowned under the flood of lines on stdout.

Redirecting is the way to go. Manually, sure, but as you probably need this functionnality through out your projects life, it is better to put this in a script. So the first idea is to add to the root of your project a small script file (say, run_doxygen.bat for Windows), that will look like this: (Nix users will adapt this without any problem)

@echo off
title Running Doxygen...

:: erasing previous files
del /Q html\*.*

:: running doxygen on file 'doxyfile.dox'
doxyfile.dox 1>doxygen_stdout.txt 2>doxygen_stderr.txt

:: showing doc (html) in default browser
html\index.html

:: opening error file in default text editor
doxygen_stderr.txt

This way, you log in two separate files the streams stdout and stderr, the latter being automatically opened when done, so the user can check for errors.

However, this method has two disadvantages:

• First, doxyfile name is hardcoded. For medium to large size projects, we will often have several configuration files, depending of the current documentation needs. Sure, whe could also duplicate the script, but that's not very practical.
• Second, this has to be done for every project we handle.

So a better idea is to have a unique script file somewhere, (on windows, c:\program files\_script for instance), and to associate the doxyfile type to this script, and not to the doxygen binary!

This only difference with the previous version is that it needs to explicitly call the doxygen binary, and pass it the script argument (%1) (doxygen configuration file).

@echo off
title Running Doxygen...

:: erasing previous files
del /Q html\*.*

:: running doxygen
"c:\program files\doxygen\bin\doxygen.exe" "%1" 1>doxygen_stdout.txt 2>doxygen_stderr.txt

:: showing doc (html) in default browser
html\index.html

:: opening error file in default text editor
doxygen_stderr.txt

Don't forget the quotes around the doxygen binary path !

Edit: this is for "html" doxygen output, but you can adapt it easily for other output types (tex, man, rtf, ...)

Edit-2 (2010-11-12): Actually, you must not put quotes around the %1 argument. Windows automatically adds quotes to the argument when called through the explorer, and this causes problem if the doxyfile is located from a path that has spaces.
(yes, I know, nobody puts spaces in the path of his personal folders...)