Changes between Version 65 and Version 66 of DoxygenPlugin
- Timestamp:
- Mar 18, 2015, 10:01:03 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DoxygenPlugin
v65 v66 1 1 [[PageOutline(2-5,Contents,pullout)]] 2 2 3 = Doxygen Plugin for Trac =4 5 == Description ==3 = Doxygen Plugin for Trac 4 5 == Description 6 6 7 7 Integrates [http://www.stack.nl/~dimitri/doxygen/ doxygen] documentation into Trac. 8 8 9 The aim is to embed one or multiple doxygen-generated documentation(s) within Trac, 10 in order to have consistent look and feel, and easy referencing to doxygen pages 11 using the usual TracLinks and the `doxygen:` prefix. 12 13 The doxygen plugin provides a new main navigation tab (named ''Doxygen'' by default), 14 which will present an index page. 15 If you have to present only one documentation project, that index page can directly 16 be a Doxygen-generated page, like the index.html, main.html (default) or hierarchy.html. 17 An alternative is to pick a Wiki page to use as the index, and this is indeed the best 18 option if you have multiple documentation projects to serve. That way you can build 19 your own ''meta'' index the way you want, using `doxygen:...` links within that page. 20 21 Configuring the Doxygen plugin should be easy if you have only one Doxygen generated 22 documentation to wrap, and a bit more involved if you have many --but the goal is to 23 have a great deal of flexibility, in the latter case. 9 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. 10 11 The doxygen plugin provides a new main navigation tab (named ''Doxygen'' by default), which will present an index page. 12 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. 13 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. 14 15 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. 24 16 25 17 This plugin is compatible with the following releases of Trac: … … 27 19 - 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. 28 20 29 Th e rest of this documentation is covering both versions, but is probablymore accurate for the latter.30 31 == Bugs/Feature Requests ==21 This documentation covers both versions, but is more accurate for the latter. 22 23 == Bugs/Feature Requests 32 24 33 25 Existing bugs and feature requests for DoxygenPlugin are [report:9?COMPONENT=DoxygenPlugin here]. If you have any issues, create a 34 26 [/newticket?component=DoxygenPlugin&owner=cboos new ticket] but read BugReporting page first, please. 35 27 36 == Source == 28 [[TicketQuery(component=DoxygenPlugin&group=type,format=progress)]] 29 30 == Source 37 31 38 32 You can check out the source for DoxygenPlugin [/svn/doxygenplugin using Subversion], … … 41 35 Download the zipped source for the appropriate branch: [download:doxygenplugin/0.9 0.9], [download:doxygenplugin/0.10 0.10], [download:doxygenplugin/0.11 0.11]. 42 36 43 == Example ==37 == Example 44 38 45 39 An example use of the DoxygenPlugin can be seen on the [http://developer.pidgin.im/doxygen/ Pidgin] site. 46 40 47 == Installation ==48 49 Choose to install the plug-in either manually or automatically. In either case, you may need to restart web server to see Doxygen button in navigation tab.50 51 === Manual ===41 == Installation 42 43 Choose to install the plug-in 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. 44 45 === Manual 52 46 53 47 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. … … 62 56 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. 63 57 64 === Automatic ===65 66 Using easy_install to fetch, build , and install.58 === Automatic 59 60 Using easy_install to fetch, build and install: 67 61 68 62 {{{ … … 71 65 }}} 72 66 73 For reference, below is an example console output for Ubuntu 9.10:67 Example console output for Ubuntu 9.10: 74 68 75 69 {{{ … … 86 80 }}} 87 81 88 === Configuring Trac === 89 90 ==== Basic Configuration ==== 82 === Configuring Trac 83 84 ==== Basic Configuration 85 91 86 A `[doxygen]` section should be created in TracIni. 92 There's only one mandatory setting, it's the `path` to the generated documentation. 93 This should match the [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_output_directory OUTPUT_DIRECTORY] 94 setting in the Doxyfile (if that's a relative path, you'll need to prepend the current working directory used 95 when running `doxygen`). Also, don't forget to grant the users the DOXYGEN_VIEW permission, or you'll just get a blank page. 96 97 Note that there's also the [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_output HTML_OUTPUT] 98 setting which might play a role here. By default, the value for this setting is `html`, and this will be 99 appended to the path specified in `OUTPUT_DIRECTORY`. 100 101 '''Example:''' [[br]] 87 There is only one mandatory setting, which is the `path` to the generated documentation. 88 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. 89 90 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`: 91 102 92 {{{ 103 93 #!ini … … 107 97 }}} 108 98 109 ==== Settings for Multiple Documentation Projects ==== 110 111 In this case, the `path` option is used to set a common prefix, shared by all the generated documentations. 112 You can also use `default_documentation` to specify which project should be used when no explicit path is 113 given when requesting a documentation file, when using the `doxygen:` TracLinks. 114 115 '''Example:''' [[br]] 116 Let's imagine you have two sets of documentation, one for the latest trunk, one for a stable branch, 117 and they are like this: 99 ==== Settings for Multiple Documentation Projects 100 101 When documenting multiple projects, the `path` option is used to set a common prefix, which is shared by all generated documentations. 102 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. 103 104 '''Example:''' Let's imagine you have two sets of documentation, one for the latest trunk and one for a stable branch, and they are like this: 118 105 {{{ 119 106 #!sh … … 135 122 - /var/cache/doxygen/devel/html 136 123 137 You want to have links like `doxygen:MyClass` refer to the documentation for the ''stable'' branch, 138 i.e. to be equivalent to `doxygen:stable/MyClass`. 139 To that end, you need the following setup: 124 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: 140 125 141 126 {{{ … … 158 143 }}} 159 144 160 ==== Options Summary ====161 162 These are all the configuration options recognized in the `[doxygen]` section of TracIni .163 || ''' ''Option Name''''' || '''''Documentation''''' || '''''Default value''''' ||164 || '''`path`''' || Directory containing doxygen generated files. || 145 ==== Options Summary 146 147 These are all the configuration options recognized in the `[doxygen]` section of TracIni: 148 || '''Option Name''' || '''Documentation''' || '''Default value''' || 149 || '''`path`''' || Directory containing doxygen generated files. || || 165 150 || `html_output` ||Default documentation project suffix, as generated by Doxygen using the HTML_OUTPUT Doxygen configuration setting. ''Since 0.10'' || || 166 || `title` || Title to use for the main navigation tab. || ''Doxygen''||167 || `ext` || Space separated list of extensions for doxygen managed files. || ''htm html png''||168 || `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''||169 || `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. || 170 || `index` || Default index page to pick in the generated documentation. || ''main.html''||171 || `wiki_index` || Wiki page to use as the default page for the Doxygen main page. If set, supersedes the [doxygen] index option. || 172 || `encoding` || Default encoding used by the generated documentation files. ''Since 0.10'' || ''iso-8859-1''||151 || `title` || Title to use for the main navigation tab. || Doxygen || 152 || `ext` || Space separated list of extensions for doxygen managed files. || htm html png || 153 || `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 || 154 || `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. || || 155 || `index` || Default index page to pick in the generated documentation. || main.html || 156 || `wiki_index` || Wiki page to use as the default page for the Doxygen main page. If set, supersedes the [doxygen] index option. || || 157 || `encoding` || Default encoding used by the generated documentation files. ''Since 0.10'' || iso-8859-1 || 173 158 ^''(up to date with r1249)''^ 174 159 175 If you install the plugin globally, you 'll also need to enable it in trac.ini as follows:160 If you install the plugin globally, you will also need to enable it in `trac.ini`: 176 161 177 162 {{{ … … 181 166 }}} 182 167 183 === Configuring Doxygen ===168 === Configuring Doxygen 184 169 185 170 The only configuration setting in the Doxyfile that is required to make this plugin work is 186 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_generate_html GENERATE_HTML]. 171 [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_generate_html GENERATE_HTML]: 172 187 173 {{{ 188 174 #!comment … … 190 176 }}} 191 177 192 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.178 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. 193 179 194 180 {{{ … … 207 193 and my !TracFooter.html contains a blank line. 208 194 209 To enable the search option, the [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_searchengine SEARCHENGINE] 210 setting must be set to `YES` (of course, calls to the php search script will be hijacked by this plugin, 211 so you don't need to bother to install/configure php ;) ). 195 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. 212 196 ---- 213 197 214 == TracLinks == 215 216 217 It's possible to create links to doxygen documentation from anywhere within a Wiki text, by using the `doxygen:` link prefix. 198 == TracLinks 199 200 It is possible to create links to doxygen documentation from anywhere within a Wiki text, by using the `doxygen:` link prefix. 218 201 219 202 The general syntax of such links is: `doxygen:documentation_path/documentation_target`, where `documentation_path` is optional. … … 237 220 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"). 238 221 239 == Recent Changes ==222 == Recent Changes 240 223 241 224 [[ChangeLog(doxygenplugin, 3)]] 242 225 243 == Feedback ==226 == Feedback 244 227 245 228 [[Poll(Are you using this plugin?; Yes, it's usefull.; No, but plan to.; No, it's useless.; No, I don't need it.)]] 246 229 247 === Defects === 230 === Defects 231 248 232 [[TicketQuery(status=!closed&component=DoxygenPlugin&type=defect)]] 249 === Wishes === 233 234 === Wishes 235 250 236 [[TicketQuery(status=!closed&component=DoxygenPlugin&type=enhancement)]] 251 237 252 == Author/Contributors ==238 == Author/Contributors 253 239 254 240 '''Author:''' [wiki:jparks] [[BR]]
