[[PageOutline(2-5,Contents,pullout)]] = Embed Doxygen-generated pages into Trac == Description [[Image(doxygen.png, align=right)]] This plugin produces and embeds one or multiple [http://doxygen.nl/ Doxygen]-generated documentation(s) within Trac, to have up-to-date documentation and easy referencing to Doxygen pages using the usual TracLinks and the `doxygen:` prefix. Doxygen itself is GPL licensed. The plugin provides a new link in the admin panel, which will present a web form version of the Doxygen standard configuration file, named ''Doxyfile'' by default. Submitting the form will archive the chosen options, and Doxygen will run immediately on them. The plugin also 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 (default), files.html etc. 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 a Doxygen generated documentation ready and no other to use, and a bit more involved if you want to use all the features. The [source:/doxygenplugin/trunk trunk] branch of this plugin is compatible with Trac >= 0.11 and Doxygen >= 1.8, and is the most recent version. '''Note''': the [source:/doxygenplugin/0.10 0.10] branch of this plugin is deprecated and the [source:/doxygenplugin/0.11 0.11] branch of this plugin is not maintained. This documentation covers all versions. == 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 [export:doxygenplugin/trunk trunk] version. == Source You can check out DoxygenPlugin from [/svn/doxygenplugin here] using Subversion, or [source:doxygenplugin 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 installation Download the source code for the DoxygenPlugin from [export:doxygenplugin here] or checkout the source from the Trac hacks subversion repository at `https://trac-hacks.org/svn/doxygenplugin`. Change to the doxygenplugin/trunk (or another version) 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. === Scripted installation Using easy_install to fetch, build and install: {{{#!sh $ sudo easy_install https://trac-hacks.org/svn/doxygenplugin/trunk/ }}} 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 }}} == 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 [http://www.doxygen.nl/manual/config.html#cfg_output_directory OUTPUT_DIRECTORY] setting in the Doxyfile. If that is a relative path, you will need to prefix 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.doxygen.nl/manual/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 }}} === 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 has `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 = - Main page for the stable documentation: [doxygen:] or [doxygen:/] or [doxygen:stable/] - Documentation for the development documentation: [doxygen:devel/] }}} === Options Summary These are all the configuration options recognized in the `[doxygen]` section of TracIni: || '''Option Name''' || '''Documentation''' || '''Default value''' || || `path` || Directory containing Doxygen ouput. || || || `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 || || `input` || Directory containing the sources. Mostly useful for Doxygen EXCLUDE option. ''(unavailable in versions <= 0.11)'' || || || `doxyfile` || Full path of the Doxyfile to be created. ''(unavailable in versions <= 0.11)'' || || || `doxygen` || Full path of the Doxygen command. ''(unavailable in versions <= 0.11)'' || `/usr/local/bin/doxygen` || || `doxygen_args` || Argument of the Doxygen command. This is usefull if you plan to include the `doxyfile` produced by the plugin from another file to override a few Doxygen options ''(unavailable in versions <= 0.11)'' || Default to the `doxyfile` option above. || || `searchdata_file` || The name of the file specified by the "SEARCHDATA_FILE" Doxygen configuration setting. ''(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 used to find the `searchdata_file` || || || `index` || Default index page to pick in the generated documentation. || index.html (main.html in versions <= 0.11) || || `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 r15362)''^ If you install the plugin globally, you will also need to enable it in your `trac.ini` file: {{{#!ini [components] doxygentrac.* = enabled }}} === Configuring Doxygen To make this plugin work, you have to set to YES the following items in the Doxyfile: [http://www.doxygen.nl/manual/config.html#cfg_generate_html GENERATE_HTML], [http://www.doxygen.nl/manual/config.html#cfg_searchenginel SEARCHENGINE], [http://www.doxygen.nl/manual/config.html#cfg_server_based_search SERVER_BASED_SEARCH] and [http://www.doxygen.nl/manual/config.html#cfg_external_search 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 files: {{{ HTML_HEADER = TracHeader.html HTML_FOOTER = TracFooter.html }}} See [http://www.doxygen.nl/manual/config.html#cfg_html_header HTML_HEADER] and [http://www.doxygen.nl/manual/config.html#cfg_html_footer HTML_FOOTER]. In versions <= 0.11, the [http://www.doxygen.nl/manual/config.html#cfg_create_subdirs 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 useful 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 [[ChangeLog(doxygenplugin, 3)]] == Author/Contributors '''Author:''' [wiki:jparks] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' Blackhex cboos