wiki:DoxygenPlugin

Version 42 (modified by anonymous, 8 years ago) (diff)

corrected a type error

Doxygen Plugin for Trac

Description

Integrates doxygen documentation into Trac.

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.

Bugs/Feature Requests

Existing bugs and feature requests for DoxygenPlugin are here.

If you have any issues, create a new ticket.

Source

You can check out the source for DoxygenPlugin from Subversion at http://trac-hacks.org/svn/doxygenplugin, or browse the source locally. See log:/doxygenplugin for recent changes.

Download the zipped source for the 0.9 branch or the 0.10 branch.

Example


Installation

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/0.10 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 outlined below.

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:

$ 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, i.e. 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

It is advised to used the wiki_index in this situation, 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
ext Space separated list of extensions for doxygen managed files. htm html png
source_ext Space separated list of source files extensions idl odl java cs py php php4 inc phtml m cpp cxx c hpp hxx h
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 iso-8859-1

(up to date with r1249)

If you install the plugin globally, you'll also need to enable it in trac.ini as follows:

[components]
doxygentrac.* = enabled

Configuring Doxygen

The only configuration setting in the Doxyfile that is required to make this plugin work is GENERATE_HTML.

Since this plugin just embeds the html pages generated by doxygen you will need to define a custom header and footer even if it will be containing only blank line.

HTML_HEADER            = TracHeader.html
HTML_FOOTER            = TracFooter.html

See HTML_HEADER and HTML_FOOTER.

These files must contain something, a blank line is sufficient, or doxygen will put in the defaults. You can put there you 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:
    • annotated, classes, dirs, files, functions, globals, hierarchy, index, inherits, main, namespaces and namespacemembers
  • the name of a documented struct or class
  • the name of a directory {o}
  • the name of a file {o}

Some examples:

[doxygen:main.html Documentation] # Simple documentation in doxygen path.

[doxygen:FirstProject/annotated Annotated List of Classes in FirstProject]
[doxygen:SecondProject/main.html Main doc index for SecondProject] 

In order to use links to documented structs or classes Doxygen needs to be configured not to generate subdirectories, see CREATE_SUBDIRS.

Recent Changes

[12233] by rjollos on 2012-10-22 01:05:28
Fixes #7247: Changed the default value for html_output to be an empty string.
[11777] by rjollos on 2012-07-25 09:46:39
Added setup.cfg.
[10461] by rjollos on 2011-07-12 08:10:24
Show plugin's svn revision on webadmin plugin panel.

Feedback

Are you using this plugin?
  • Yes, it's usefull. (sgrayban, cboos, okaori, wadeb, s0undt3ch, ttressieres, imme, dh1jc, talameelombu, Tharban, athomas, jtuchscherer, xvirus, osimons, Sincklation, manni, izzy, ericalens, KevinGabbert, mwehr, renzo, marcvs, eskil, rjollos, koolhand, edo, colski, dfleming, lucasrangit, miezuit, lhr870630, hasienda, arnisandy, lucid, AdrianFritz, akliewer99)
  • No, it's useless.
  • No, I don't need it. (dfaerch, harmy, prz)

  • You don't have permission to vote. You may need to login.

Defects

#706
scanning algorithm?
#772
Wrong link path in navigation
#868
Search for class methods
#951
Any file in the file system can be accessed via the Doxygen plugin
#962
images are not shown
#1085
Search does not work
#1564
Links on doxygen Main Page resulted in call of trac search
#1803
trac link with subdirectory access
#2702
path is leaking some sensitive infos
#2979
search does not work
#4175
HTML title should be set to a specific name
#5278
Highliting boxes around Classes/methods/functions are not shown
#5963
doxygentrac cannot cope with subdirized doxygen documentation
#6262
Search does not work with Doxygen >= 1.6.0
#7247
Trac 0.11.6 AttributeError: 'NoneType' object has no attribute 'startswith'
#7710
Pages with frames do not display correctly
#11294
Images placed in folder IMAGE_PATH are not shown

Wishes

#771
Nicer CSS
#1882
TracLinks in doxygen-comments?
#3003
IWikiSyntaxProvider with doxygen SEARCH_ENGINE unusable slow for large code-bases
#4740
Accessing the doxygen files in a subversion repository

Author/Contributors

Author: jparks
Contributors: Blackhex cboos