Context Navigation

Changes between Version 71 and Version 72 of DoxygenPlugin

Timestamp:: Feb 12, 2016, 11:16:44 AM (8 years ago)
Author:: Committo-Ergo-Sum
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

DoxygenPlugin

-                      v71
+                      v72
 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.
+ - The [source:/doxygenplugin/0.11 0.11] branch of this plugin is compatible with Trac >= 0.11 and Doxygen < 1.8; and is not maintained.
+ - The [source:/doxygenplugin/trunk 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
 …
 == 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].
+Download the zipped source for the appropriate branch: [export:doxygenplugin/0.10 0.10], [export:doxygenplugin/0.11 0.11],  [export:doxygenplugin/trunk trunk].
 == Source
 …
 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:
+Change to the doxygenplugin/trunk (or another version) directory and run:
 {{{#!sh
 …
 {{{#!sh
 $ sudo easy_install https://trac-hacks.org/svn/doxygenplugin/0.11/
+$ sudo easy_install https://trac-hacks.org/svn/doxygenplugin/trunk/
 }}}
 …
 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''. || ||
+|| `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 ||
+|| `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''. || iso-8859-1 ||
+|| `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:
 …
 === 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.
+The configuration settings in the Doxyfile that are required to make this plugin work are
+[http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_generate_html GENERATE_HTML]
+and
+[http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_searchenginel SEARCHENGINE]
+both to YES. 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):
 {{{
 …
 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 the following example:
+{{{#!css
+<style type="text/css">
+   h1 { text-align: center; }
+</style>
+}}}
+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.
+In versions <= 0.11, the [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_create_subdirs CREATE_SUBDIRS] option should be set to NO;
+this is not mandatory anymore.
 == TracLinks
 …
 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}
+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 classe, a file etc.
+Technically, it must be the content of a `field` tag having a `name` attribute equals to `name` in the `searchdata_file`.
 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]
+}}}
+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.
+[doxygen:foo] # Link to the documentation of the function (or class etc) foo in the main documentation.
+[doxygen:SecondProject/foo] similarly for another documentation
+}}}
 == Recent Changes