Changes between Version 66 and Version 67 of DoxygenPlugin


Ignore:
Timestamp:
Jun 16, 2015, 8:20:50 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged with 'documentation'

Legend:

Unmodified
Added
Removed
Modified

  • DoxygenPlugin

    v66 v67  
    55== Description
    66
    7 Integrates [http://www.stack.nl/~dimitri/doxygen/ doxygen] documentation into Trac.
    8 
    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.
     7This 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.
    108
    119The doxygen plugin provides a new main navigation tab (named ''Doxygen'' by default), which will present an index page.
    … …  
    1311An 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.
    1412
    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.
     13Configuring the Doxygen plugin is straightforward if you have only one Doxygen generated documentation to wrap, and a bit more involved if you have many.
    1614
    1715This plugin is compatible with the following releases of Trac:
    1816 - The [source:/doxygenplugin/0.10 0.10] branch of this plugin is compatible with Trac 0.10, but is ''deprecated''.
    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.
     17 - 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.
    2018
    2119This documentation covers both versions, but is more accurate for the latter.
    … …  
    2422
    2523Existing bugs and feature requests for DoxygenPlugin are [report:9?COMPONENT=DoxygenPlugin here]. If you have any issues, create a
    26 [/newticket?component=DoxygenPlugin&owner=cboos new ticket] but read BugReporting page first, please.
     24[/newticket?component=DoxygenPlugin new ticket] but read BugReporting page first, please.
    2725
    2826[[TicketQuery(component=DoxygenPlugin&group=type,format=progress)]]
    2927
     28== Download
     29
     30Download 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].
     31
    3032== Source
    3133
    32 You can check out the source for DoxygenPlugin [/svn/doxygenplugin using Subversion],
     34You can check out the source for this plugin using [/svn/doxygenplugin Subversion],
    3335or [browser:/doxygenplugin browse] the source locally. See log:/doxygenplugin for recent changes.
    3436
    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].
    36 
    3737== Example
    3838
    … …  
    4141== Installation
    4242
    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.
     43Install 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.
    4444
    4545=== Manual
    4646
    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.
     47Download 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`.
    4848
    4949Change to the doxygenplugin/0.10 directory and run:
    5050
    51 {{{
    52 #!sh
    53 python setup.py bdist_egg
    54 }}}
    55 
    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.
     51{{{#!sh
     52$ python setup.py bdist_egg
     53}}}
     54
     55This will generate a Python egg in the dist directory. Copy the egg file into the `trac/plugins` directory and follow the Configuration steps below.
    5756
    5857=== Automatic
    … …  
    6059Using easy_install to fetch, build and install:
    6160
    62 {{{
    63 #!sh
     61{{{#!sh
    6462$ sudo easy_install http://trac-hacks.org/svn/doxygenplugin/0.11/
    6563}}}
    … …  
    6765Example console output for Ubuntu 9.10:
    6866
    69 {{{
    70 #!sh
     67{{{#!sh
    7168Downloading http://trac-hacks.org/svn/doxygenplugin/0.11/
    7269Doing subversion checkout from http://trac-hacks.org/svn/doxygenplugin/0.11/ to /tmp/easy_install-CIE2Es/0.11
    … …  
    9087Note 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`:
    9188
    92 {{{
    93 #!ini
     89{{{#!ini
    9490[doxygen]
    9591path = /var/cache/doxygen/myproject
    … …  
    10096
    10197When 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:
    105 {{{
    106 #!sh
     98
     99Suppose 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`.
     100
     101'''Example:''' Imagine you have two sets of documentation, one for the latest trunk and one for a stable branch, and they are like this:
     102{{{#!sh
    107103$ cd /var/cache/doxygen
    108104$ grep OUTPUT Doxyfile.stable
    … …  
    124120You 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:
    125121
    126 {{{
    127 #!ini
     122{{{#!ini
    128123[doxygen]
    129124path = /var/cache/doxygen
    … …  
    133128}}}
    134129
    135 It is advised to used the `wiki_index` in this situation, so you can place links to both documentation sets:
     130In this situation use the `wiki_index` , so you can place links to both documentation sets:
    136131{{{
    137132= Documentation generated by Doxygen =
    … …  
    148143|| '''Option Name''' || '''Documentation''' || '''Default value''' ||
    149144|| '''`path`''' || Directory containing doxygen generated files. ||  ||
    150 || `html_output` ||Default documentation project suffix, as generated by Doxygen using the HTML_OUTPUT Doxygen configuration setting. ''Since 0.10'' || ||
     145|| `html_output` ||Default documentation project suffix, as generated by Doxygen using the HTML_OUTPUT Doxygen configuration setting. ''Since 0.10''. || ||
    151146|| `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 ||
     147|| `ext`        || Space separated list of extensions for doxygen managed files. || htm html png ||
     148|| `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 ||
    154149|| `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. ||   ||
    155150|| `index`      || Default index page to pick in the generated documentation. || main.html ||
    156151|| `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 ||
     152|| `encoding`   || Default encoding used by the generated documentation files. ''Since 0.10''. || iso-8859-1 ||
    158153^''(up to date with r1249)''^
    159154
    160 If you install the plugin globally, you will also need to enable it in `trac.ini`:
    161 
    162 {{{
    163 #!ini
     155If you install the plugin globally, you will also need to enable it in your `trac.ini` file:
     156{{{#!ini
    164157[components]
    165158doxygentrac.* = enabled
    … …  
    171164[http://www.stack.nl/~dimitri/doxygen/config.html#cfg_generate_html GENERATE_HTML]:
    172165
    173 {{{
    174 #!comment
     166{{{#!comment
    175167GENERATE_TREEVIEW doesn't seem to be needed... Why was this part of the mandatory settings?
    176168}}}
    … …  
    182174HTML_FOOTER            = TracFooter.html
    183175}}}
     176
    184177See [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_header HTML_HEADER]
    185178and [http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_footer HTML_FOOTER].
    186179
    187 These files must contain something, a blank line is sufficient, or doxygen will put in the defaults. You can put there your own CSS style as in following example:
    188 {{{
     180These 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:
     181{{{#!css
    189182<style type="text/css">
    190183        h1 { text-align: center; }
    191184</style>
    192185}}}
     186
    193187and my !TracFooter.html contains a blank line.
    194188
    195189To 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.
    196 ----
    197190
    198191== TracLinks