[[PageOutline(2-5,Contents,pullout)]] = Doxygen Plugin for Trac == Description This plugin embeds one or multiple [http://www.stack.nl/~dimitri/doxygen/ doxygen]-generated documentation(s) within Trac, 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 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 [source:/doxygenplugin/0.10 0.10] branch of this plugin is compatible with Trac 0.10, but is ''deprecated''. - The [source:/doxygenplugin/0.11 0.11] branch of this plugin is compatible with Trac 0.11, 0.12 and 1.0+; and is being maintained. This documentation covers both versions, but is more accurate for the latter. == Bugs/Feature Requests Existing bugs and feature requests for DoxygenPlugin are [report:9?COMPONENT=DoxygenPlugin here]. If you have any issues, create a [/newticket?component=DoxygenPlugin new ticket]. [[TicketQuery(component=DoxygenPlugin,group=type,format=progress)]] == Download Download the zipped source for the appropriate branch: [export:doxygenplugin/0.9 0.9], [export:doxygenplugin/0.10 0.10], [export:doxygenplugin/0.11 0.11]. == Source You can check out DoxygenPlugin from [/svn/doxygenplugin here] using Subversion, or [browser:/doxygenplugin browse the source] using 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 [export:doxygenplugin 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: {{{#!sh $ 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: {{{#!sh $ sudo easy_install http://trac-hacks.org/svn/doxygenplugin/0.11/ }}} Example console output for Ubuntu 9.10: {{{#!sh 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 }}} === Configuring Trac ==== 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 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_output_directory 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 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_output 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`: {{{#!ini [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: {{{#!sh $ 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: {{{#!ini [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 || || `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 will also need to enable it in your `trac.ini` file: {{{#!ini [components] doxygentrac.* = enabled }}} === Configuring Doxygen The only configuration setting in the Doxyfile that is required to make this plugin work is [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_generate_html GENERATE_HTML]: {{{#!comment GENERATE_TREEVIEW doesn't seem to be needed... Why was this part of the mandatory settings? }}} Since this plugin embeds the html pages generated by doxygen, you will need to define a custom header and footer, even if it contains only a blank line. {{{ HTML_HEADER = TracHeader.html HTML_FOOTER = TracFooter.html }}} See [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_header HTML_HEADER] and [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_footer HTML_FOOTER]. These files must contain something, a blank line is sufficient, or else doxygen will put in the defaults. You can put there your own CSS style as in following example: {{{#!css }}} and my !TracFooter.html contains a blank line. To enable the search option, the [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_searchengine SEARCHENGINE] setting must be set to `YES`. Of course, calls to the PHP search script will be hijacked by this plugin, so there is no need to have PHP installed. == 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 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 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_create_subdirs CREATE_SUBDIRS]. Also filenames generated must be case sensitive, preserving the original casing ([http://www.stack.nl/~dimitri/doxygen/config.html#cfg_case_sense_names CASE_SENSE_NAMES] must be set to "YES"). == Example An example use of the DoxygenPlugin can be seen on the [http://developer.pidgin.im/doxygen/ Pidgin] site. == Recent Changes [[ChangeLog(doxygenplugin, 3)]] == 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:''' [wiki:jparks] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' Blackhex cboos