Context Navigation

Doxygen Plugin for Trac

Description

The aim is to embed one or multiple doxygen-generated documentation(s) within Trac,
in order to have consistent look and feel, and easy referencing to doxygen pages
using the usual TracLinks and the doxygen: prefix.

The doxygen plugin provides a new main navigation tab (named Doxygen by default),
which will present an index page.
If you have to present only one documentation project, that index page can directly
be a Doxygen-generated page, like the index.html, main.html (default) or hierarchy.html.
An alternative is to pick a Wiki page to use as the index, and this is indeed the best
option if you have multiple documentation projects to serve. That way you can build
your own meta index the way you want, using doxygen:... links within that page.

Configuring the Doxygen plugin should be easy if you have only one Doxygen generated
documentation to wrap, and a bit more involved if you have many --but the goal is to
have a great deal of flexibility, in the latter case.

This plugin is compatible with the following releases of Trac:

Trac ​0.9:
the 0.9​ compatible version of this plugin is in maintenance mode,
and probably no new feature will be added there.

Trac ​0.10:
the 0.10​ version of this plugin is in overhaul mode,
and this is currently in a work-in-progress-but-usable status (r1245).

The rest of this documentation is covering both versions, but is probably more accurate for the latter.

This will generate a python egg in the dist directory. Copy the egg file into the trac/plugins directory and follow the Configuration steps outlined below.

You may need to restart web server to see Doxygen button in navigation tab.

Configuring Trac

Basic Configuration

A [doxygen] section should be created in TracIni.
There's only one mandatory setting, it's the path to the generated documentation.
This should match the ​OUTPUT_DIRECTORY
setting in the Doxyfile (if that's a relative path, you'll need to prepend the current working directory used
when running doxygen). Also, don't forget to grant the users the DOXYGEN_VIEW permission, or you'll just get a blank page.

Note that there's also the ​HTML_OUTPUT
setting which might play a role here. By default, the value for this setting is html, and this will be
appended to the path specified in OUTPUT_DIRECTORY.

Example:

[doxygen]
path = /var/cache/doxygen/myproject
html_output = html

Settings for Multiple Documentation Projects

In this case, the path option is used to set a common prefix, shared by all the generated documentations.
You can also use default_documentation to specify which project should be used when no explicit path is
given when requesting a documentation file, when using the doxygen:TracLinks.

Example:
Let's imagine you have two sets of documentation, one for the latest trunk, one for a stable branch,
and they are like this:

These files must contain something, a blank line is sufficient, or doxygen will put in the defaults. You can put there your own CSS style as in following example:

<style type="text/css">
h1 { text-align: center; }
</style>

and my TracFooter.html contains a blank line.

To enable the search option, the ​SEARCHENGINE
setting must be set to YES (of course, calls to the php search script will be hijacked by this plugin,
so you don't need to bother to install/configure php ;) ).

It's possible to create links to doxygen documentation from anywhere within a Wiki text, by using the doxygen: link prefix.

The general syntax of such links is: doxygen:documentation_path/documentation_target, where documentation_path is optional.
If documentation_path is not specified, the [doxygen] default_documentation setting will be used instead.

The documentation_target part is used for specifying what Doxygen generated content will be displayed when following the link. It can be:

the name of one of the many documentation summary page generated by Doxygen:

In order to use links to documented structs or classes Doxygen needs to be configured not to generate subdirectories, see ​CREATE_SUBDIRS. Also filenames generated must be case sensitive, preserving the original casing (​CASE_SENSE_NAMES must be set to "YES").