Doxygen Plugin

Plugin containing for linking to Doxygen-generated diagrams

Plugin Preferences

Note: This plugin does not read settings from this topic. Copy the settings below to your SitePreferences topic and remove the # if changes are required. These settings can be placed in SitePreferences, WebPreferences, User topics, or any individual topic. Refer to preference settings for more information.

   * #Set DOXYGENPLUGIN_CREATE_SUBDIRS = 0
   * #Set DOXYGENPLUGIN_CASE_SENSE_NAMES = 0

Description of the settings

All settings are prefixed with DOXYGENPLUGIN_ as shown above The prefix is ommited from this table to improve layout.

The settings that appear here are meant to be set the same as the Doxygen configuration used to produce the files being linked to. Only settings relevant to the generation of output files are supported.

Note: Doxygen documentation generated with SHORT_NAMES enabled can not be supported by this plugin as those names are generated using a counter that can't reliably be reproduced outside of doxygen.

Setting	Default	Description
CREATE_SUBDIRS	0	Matches the setting of the same name in the Doxyfile configuration for Doxygen, i.e. a subdirectory hash is used to spread the output files out.
CASE_SENSE_NAMES	0	Matches the setting of the same name in the Doxyfile configuration for Doxygen, i.e. a subdirectory hash is used to spread the output files out.

Macros

DOX{...} -- renders a URL for a Doxygen class diagram

• Parameters:

  Parameter	Description	Default
  	Name of structure to link to	none, required parameter
  subdir	A simple subdirectory from the root	no subdirectory
  subdirs	Equivalent to CREATE_SUBDIRS parameter to Doxygen	DOXYGENPLUGIN_CREATE_SUBDIRS preference setting
  casesense	Equivalent to CASE_SENSE_NAMES parameter to Doxygen	DOXYGENPLUGIN_CASE_SENSE_NAMES preference setting
  stype	Structure type, e.g. "class", "struct", "union", etc.	class
  extension	File extension for Doxygen document.	.html

This macro renders to a simple text string that is the concatenation of the following elements:

• $Foswiki::cfg{Plugins}{DoxygenPlugin}{Root}
• subdir
• stype
• DEFAULT (this is the unnamed argument to the macro)
• extension

Note: For security reasons, subdir only allows alphanumeric characters and underlines. This helps prevent malicious URLs from being generated.

Note: The URL is processed through the Doxygen character escaping algorithm, which replaces potentially problematic characters with coded text.

An example:

%DOX{"std::string" subdirs="1" subdir="stdcpp" casesense="0" stype="class"}%

Would generate (with the "Root" configuration item unset):

/stdcpp/d8/d29/classstd_1_1string.html

or, with the Root set to "http://www.google.com":

http://www.google.com/stdcpp/d8/d29/classstd_1_1string.html

DOXYDOT{...} -- renders a URL for a Doxygen class diagram

• Parameters:

  Parameter	Description	Default
  	Name of structure to link to	none, required parameter
  subdir	A simple subdirectory from the root	no subdirectory
  subdirs	Equivalent to CREATE_SUBDIRS parameter to Doxygen	DOXYGENPLUGIN_CREATE_SUBDIRS preference setting
  casesense	Equivalent to CASE_SENSE_NAMES parameter to Doxygen	DOXYGENPLUGIN_CASE_SENSE_NAMES preference setting
  stype	Structure type, e.g. "class", "struct", "union", etc.	class
  gtype	Type of diagram being linked to, "coll" (collaboration) or "inherit" (inheritance)	coll
  style	Graph type, e.g. "graph", "puml"	graph (is used for Graphviz-generated diagrams while "puml" is used for PlantUML-generated diagrams)
  format	Format of the image files being linked to, e.g. "png", "svg", etc.	png

This macro renders to a simple text string that is the concatenation of the following elements:

• $Foswiki::cfg{Plugins}{DoxygenPlugin}{Root}
• subdir
• stype
• DEFAULT (this is the unnamed argument to the macro)
• "_"
• gtype
• "_"
• style
• "."
• format

Note: For security reasons, subdir only allows alphanumeric characters and underlines. This helps prevent malicious URLs from being generated.

Note: The URL is processed through the Doxygen character escaping algorithm, which replaces potentially problematic characters with coded text.

An example:

%DOXYDOT{"std::string" subdirs="1" subdir="stdcpp" casesense="0" stype="class" gtype="inherit" style="graph" format="png"}%

Would generate (with the "Root" configuration item unset):

/stdcpp/classstd_1_1string_inherit_graph.png

or, with the Root set to "http://www.google.com":

http://www.google.com/stdcpp/classstd_1_1string_inherit_graph.png

Configuration Settings

The following settings can be defined in configure (admin interface):

Setting	Description	Default
{Plugins}{DoxygenPlugin}{Root}	The top-level URL for the Doxygen documents	none (blank)

See DOXYDOT above for an explanation as to how this is used.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Installation

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

This plug-in does not require any additional modules or tools beyond the base Foswiki install and core Perl packages, however, the plug-in is not useful unless you are generating Doxygen documentation and making it available via the web.

Linking to PlantUML diagrams requires an updated Doxygen. Support for auto-generated PlantUML diagrams has not yet been integrated as of Doxygen 1.8.10. Please see the attached patch files if this function is desired. To apply the patch and build Doxygen, do the following for 1.8.9.1:

[/tmp]$ tar -xzf doxygen-1.8.9.1.src.tar.gz
[/tmp]$ cd doxygen-1.8.9.1
[/tmp]$ patch -p1 <../doxygen-1.8.9.1-table-plantuml.patch
[/tmp/doxygen-1.8.9.1]$ ./configure --prefix /usr/local
[/tmp/doxygen-1.8.9.1]$ make
[/tmp/doxygen-1.8.9.1]$ sudo make install
[/tmp/doxygen-1.8.9.1]$ cd ..
[/tmp]$ rm -rf doxygen-1.8.9.1

or for 1.8.10:

[/tmp]$ tar xzvf doxygen-1.8.10.src.tar.gz
[/tmp]$ cd doxygen-1.8.10
[/tmp/doxygen-1.8.10]$ patch -p1 <../doxygen-1.8.10-table-plantuml.patch 

The remaining steps are taken from http://www.doxygen.com/install.html (consult this page for building instructions for other platforms).

[/tmp/doxygen-1.8.10]$ mkdir build
[/tmp/doxygen-1.8.10]$ cd build
[/tmp/doxygen-1.8.10]$ cmake -G "Unix Makefiles" ..
[/tmp/doxygen-1.8.10]$ make
[/tmp/doxygen-1.8.10]$ sudo make install

Plugin Info

Change History:
13 Aug 2015	1.0.0 Initial release