[[PageOutline]] = Doxygen Plugin for Trac = == Description == Integrates [http://www.stack.nl/~dimitri/doxygen/ 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. == Bugs/Feature Requests == Existing bugs and feature requests for DoxygenPlugin are [report:9?COMPONENT=DoxygenPlugin here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=DoxygenPlugin&owner=cboos new ticket]. == Download == Download the zipped source from [download:doxygenplugin here]. == Source == You can check out the source for DoxygenPlugin from Subversion at http://trac-hacks.org/svn/doxygenplugin. == Example == === Installation === Download the source code for the DoxygenPlugin from [download:doxygenplugin here] or checkout the source from the trac hacks subversion repository at: http://trac-hacks.org/svn/doxygenplugin. Change to the doxygenplugin/0.9 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 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_output_directory OUTPUT_DIRECTORY] setting in the Doxyfile. ==== 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 are given when requesting a documentation file, when using the `doxygen:` TracLinks. '''Example:''' [[br]] Let's imagine you have two sets of documentation, one for the latest trunk, one for a stable branch, and they are generated at the following locations: - /var/cache/doxygen/devel - /var/cache/doxygen/stable 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`. {{{ [doxygen] path = /var/cache/doxygen default_documentation = stable wiki_index = DoxyGen }}} 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. || || 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. || ''iso-8859-1'' || ^^''(the above is in sync with r1245''^^ If you want to change main navigation menu button label put this to ![doxygen] section in trac.ini: {{{ [doxygen] title = Documentation }}} 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 tags that are required in to make this plugin work are '{{{GENERATE_HTML}}}' and '{{{GENERATE_TREEVIEW}}}'. 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 }}} 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: {{{ }}} and my !TracFooter.html contains a blank line. To enable the search option the {{{SEARCHENGINE}}} tag must be set to 'YES'. == Wiki Macros == Using provided wiki macro you can make a link to doxygen documentation page wherever you want. Specified links are related to setted up doxygen path: {{{ [doxygen:main.html Documentation] # Simple documentation in doxygen path. [doxygen:FirstProject/main.html First] # Multiple documentation in separate [doxygen:SecondProject/main.html Second] # directories in doxygen path. }}} == Feedback == [[Poll(Are you using this plugin?; Yes, it's usefull.; No, it's useless.; No, I don't need it.)]] == Change Log == [[ChangeLog(/doxygenplugin, 5)]] == Author/Contributors == '''Author:''' [wiki:jparks] [[BR]] '''Contributors:''' Blackhex cboos