Embed Doxygen-generated pages into Trac

Description

This plugin embeds one or multiple ​doxygen-generated documentation(s) within Trac, to have a consistent look and feel, and easy referencing to Doxygen pages using the usual TracLinks and the doxygen: prefix.

The 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 is straightforward if you have only one Doxygen generated documentation to wrap, and a bit more involved if you have many.

This plugin is compatible with the following releases of Trac:

• The 0.10​ branch of this plugin is compatible with Trac 0.10, but is deprecated.
• The 0.11​ branch of this plugin is compatible with Trac >= 0.11 and Doxygen < 1.8; and is not maintained.
• The trunk​ branch of this plugin is compatible with Trac >= 0.11 and Doxygen >= 1.8, and is under development.

This documentation covers all versions.

Bugs/Feature Requests

Existing bugs and feature requests for DoxygenPlugin are here.

If you have any issues, create a new ticket.

defect	47 / 50
enhancement	10 / 14
task	3 / 3

Download

Download the zipped source for the appropriate branch: 0.10, 0.11, trunk.

Source

You can check out DoxygenPlugin from here using Subversion, or browse the source​ with Trac.

Installation

Install the plugin either manually or automatically. In either case, you may need to restart the web server to see the Doxygen button in the navigation menu bar.

Manual

Download the source code for the DoxygenPlugin from here or checkout the source from the Trac hacks subversion repository at http://trac-hacks.org/svn/doxygenplugin.

Change to the doxygenplugin/trunk (or another version) directory and run:

$ python setup.py bdist_egg

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

Automatic

Using easy_install to fetch, build and install:

$ sudo easy_install https://trac-hacks.org/svn/doxygenplugin/trunk/

Example console output for Ubuntu 9.10:

Downloading http://trac-hacks.org/svn/doxygenplugin/0.11/
Doing subversion checkout from http://trac-hacks.org/svn/doxygenplugin/0.11/ to /tmp/easy_install-CIE2Es/0.11
Processing 0.11
Running setup.py -q bdist_egg --dist-dir /tmp/easy_install-CIE2Es/0.11/egg-dist-tmp-88Ruf4
unrecognized .svn/entries format in 
Adding TracDoxygen 0.11.0.2 to easy-install.pth file

Installed /usr/local/lib/python2.6/dist-packages/TracDoxygen-0.11.0.2-py2.6.egg
Processing dependencies for TracDoxygen==0.11.0.2

Configuration

Basic Configuration

A [doxygen] section should be created in TracIni. There is only one mandatory setting, which is the path to the generated documentation. This should match the ​OUTPUT_DIRECTORY setting in the Doxyfile. If that is a relative path, you will need to prepend the current working directory used when running doxygen. Also, don't forget to grant the users the DOXYGEN_VIEW permission, else a blank page will be returned.

Note that there is 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:

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

Settings for Multiple Documentation Projects

When documenting multiple projects, the path option is used to set a common prefix, which is shared by all generated documentations.

Suppose you are requesting a documentation file that have the doxygen: TracLinks embedded. To specify which project should be used when no explicit path is given, you can also use default_documentation.

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

$ cd /var/cache/doxygen
$ grep OUTPUT Doxyfile.stable
OUTPUT_DIRECTORY = stable
HTML_OUTPUT = html
$ grep OUTPUT Doxyfile.devel
OUTPUT_DIRECTORY = devel
HTML_OUTPUT = html
$ doxygen Doxyfile.stable
...
$ doxygen Doxyfile.devel
...

Now, you will have the following directory structure:

• /var/cache/doxygen/stable/html
• /var/cache/doxygen/devel/html

You want to have links like doxygen:MyClass refer to the documentation for the stable branch, ie to be equivalent to doxygen:stable/MyClass. To that end, you need the following setup:

[doxygen]
path = /var/cache/doxygen
default_documentation = stable
wiki_index = DoxyGen
html_output = html

In this situation use the wiki_index , so you can place links to both documentation sets:

= Documentation generated by Doxygen =

 - Documentation for the stable API: 
   [doxygen:stable/hierarchy class hierarchy], [doxygen:stable/dirs directory hierarchy]
 - Documentation for the trunk API: 
   [doxygen:devel/hierarchy class hierarchy], [doxygen:devel/dirs directory hierarchy]

Options Summary

These are all the configuration options recognized in the [doxygen] section of TracIni:

Option Name	Documentation	Default value
path	Directory containing doxygen generated files.
html_output	Default documentation project suffix, as generated by Doxygen using the HTML_OUTPUT Doxygen configuration setting. (Since 0.10).
title	Title to use for the main navigation tab.	Doxygen
searchdata_file	the name of the file specified by the "SEARCHDATA_FILE" option of DOXYGEN. (unavailable in versions <= 0.11)	searchdata.xml
default_documentation	Default documentation project, relative to [doxygen] path. When no explicit path is given in a documentation request, this path will be prepended to the request before looking for documentation files.
index	Default index page to pick in the generated documentation.	main.html
wiki_index	Wiki page to use as the default page for the Doxygen main page. If set, supersedes the [doxygen] index option.
encoding	Default encoding used by the generated documentation files. (Since 0.10).	utf-8 (iso-8859-1 in versions <= 0.11)
ext	Space separated list of extensions for doxygen managed files. (deprecated after version 0.11)	htm html png
source_ext	Space separated list of source files extensions. (deprecated after version 0.11)	idl odl java cs py php php4 inc phtml m cpp cxx c hpp hxx h

^{(up to date with r1249)}

If you install the plugin globally, you will also need to enable it in your trac.ini file:

[components]
doxygentrac.* = enabled

Configuring Doxygen

To make this plugin work, you have to set to YES the following items in the Doxyfile: ​GENERATE_HTML, ​SEARCHENGINE, ​SERVER_BASED_SEARCH and ​EXTERNAL_SEARCH. Note that calls to the search engine used by Doxygen will be hijacked by the Trac search engine.

You may replace the standard Doxygen header and footer HTML by your own (this was mandatory in versions <= 0.11, even if they contain only a blank line):

HTML_HEADER            = TracHeader.html
HTML_FOOTER            = TracFooter.html

See ​HTML_HEADER and ​HTML_FOOTER.

In versions <= 0.11, the ​CREATE_SUBDIRS option should be set to NO; this is not mandatory anymore.

TracLinks

It is 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 must be a name for which a documentation was produced by Doxygen, depending on the way you ran it. Most of the time, it will be a function, a class, a file etc. Technically, it must be the content of a field tag having a name attribute equals to name in the searchdata_file. If the name is empty, the link leads to the main page of the documentation; this is usefull to give access to the main page of a documentation which is not the default one (for example the Wiki page of a project may list the documentations of the older versions with these links).

Some examples:

[doxygen:foo] # Link to the documentation of the function (or class etc) foo in the main documentation.
[doxygen:SecondProject/foo] similarly for another documentation.
[doxygen:] or [doxygen:/] Main page of the documentation.
[doxygen:SecondProject/] Main page of the second project documentation.

Recent Changes

18471 by rjollos on 2022-04-06 23:39:11

DoxygenPlugin 0.7.5dev: Make compatible with Python 3

Patch by anonymous.

Refs #14123.

17631 by rjollos on 2019-12-18 19:03:49

DoxygenPlugin 0.7.5dev: Make compatible with Trac 1.0+

Fixes #13710.

16397 by rjollos on 2017-03-25 09:37:00

Remove obsolete "0.9" code

(more)

Feedback

Poll(Are you using this plugin?; Yes, it's usefull.; No, but plan to.; No, it's useless.; No, I don't need it.)?

Author/Contributors

Author: jparks
Maintainer: Committo-Ergo-Sum
Contributors: Blackhex cboos