Tags:
automation1Add my vote for this tag development1Add my vote for this tag documentation1Add my vote for this tag import1Add my vote for this tag create new tag
, view all tags

Doxygen Import Plugin

Import Doxygen documentation into TWiki by uploading a ZIP file containing Doxygen-generated files

Introduction

Screenshot
Doxygen is a tool to generate documentation from annotated source code of C, C++ and other languages. Output can be HTML, LATEX, RTF (MS-Word), PostScript, hyperlinked PDF, and Unix man pages.

Use the DoxygenImportPlugin to import a set of Doxygen generated HTML pages into TWiki.

You can automate the documentation of your software products by first importing Doxygen generated documentation into a TWiki, then use the TWiki:Plugins.PublishWebPlugin to publish Doxygen docs and other documentation to your website.

Usage

1. Generate Doxygen Docs

Use Doxygen to generate HTML documentation from your library. The example we use here is "CRL" (Common Runtime Library). Doxygen creates .html HTML files, .png image files, .css style sheets, and .js JavaScript files in a single directory. The index.html file is the start page that contains navigation to the generated documentation.

2. Create ZIP Archive File

Create a ZIP archive file of all files Doxygen generated for your library. Example: CRL-docs.zip

3. Create Base Topic

Create a base topic in the web where you want to import the Doxygen documentation. This is the main page of your library documentation. The name is significant - use a short form of your library, such as topic name CRL. At a minimum add this content to the topic:

%DOXYGENIMPORT{navigation}%
%STOPPUBLISH%
---++!! Import Doxygen Documentation
%DOXYGENIMPORT{import}%

Notes:

  • The %DOXYGENIMPORT{navigation}% expands to the navigation that was in the generated index.html file.
  • The %STOPPUBLISH% directs the PublishWebPlugin to not publish content below this point. Only needed if you use the PublishWebPlugin.
  • The %DOXYGENIMPORT{import}% expands to a form that you can use to import the Doxygen archive file.

4. Create Doxygen Template Topic

The DoxygenImportPlugin uses a template topic as a base for generated topics. It will search for a template topic in the following order:

  • template parameter in DOXYGENIMPORT variable, such as %DOXYGENIMPORT{ "import" template="DoxygenTemplate"}%
  • {Plugins}{DoxygenImportPlugin}{TemplateTopic} configure setting
  • Existing topic, such as CRL_globals for globals.html file
  • Base topic, such as CRL
  • WebTopicEditTemplate in the current web
  • WebTopicEditTemplate in the Main web
  • WebTopicEditTemplate in the TWiki06x00 web

Creating a custom Doxygen template topic is optional - use it if you want to have some control over the output format.

The usual TWiki variables are expanded on topic creation. In addition, the following variables are expanded:

  • %DOXYGENTEXT% - generated text
  • %DOXYGENTITLE% - generated title

Notes:

  • The template topic text is ignored if %DOXYGENTEXT% is missing. However, a TWiki form present in a template topic is used.
  • If the TWiki form has a form field called "Title", its value is set to the generated title.

5. Import Doxygen Documentation

Use the import Doxygen archive form in the base page to upload the ZIP file, in our example CRL-docs.zip. Depending on the size of your library, the import may take some time. This generates a set of topics.

The name of generated topics is composed of base topic name, an underscore and the html file name. For example, for base topic CRL, the globals.html file turns into topic CRL_globals. As an exception, index.html turns into just CRL, e.g. the base topic name that was created in step 3.

Notes:

  • The import of a library documentation can be repeated as needed to sync changes back into TWiki.
  • Obsolete topics will be removed, e.g. for a CRL library, the plugin will remove any CRL_* topics that have no corresponding HTML file in the uploaded Doxygen archive.

Syntax Rules

1. %DOXYGENIMPORT{"import"}% - show form to import Doxygen archive file

Parameter Explanation Default
"import" Show a form to import a Doxygen archive file "navigation"
template="..." Template topic to use as a base for generated topics {Plugins}{DoxygenImportPlugin}{TemplateTopic} configure setting

2. %DOXYGENIMPORT{"navigation"}% - show navigation of the base page

Parameter Explanation Default
"navigation" Show navigation of the base page This is the default

Installation & Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

1. Plugin Installation:

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip DoxygenImportPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/DoxygenImportPlugin.txt Plugin topic
      data/TWiki/VarDOXYGENIMPORT.txt Variable documentation topic
      pub/TWiki/DoxygenImportPlugin/*png Screenshots
      lib/TWiki/Plugins/DoxygenImportPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/DoxygenImportPlugin/Core.pm Plugin core module
      lib/TWiki/Plugins/DoxygenImportPlugin/Config.spec Configure spec file
    • Set the ownership of the extracted directories and files to the webserver user.

2. Plugin Configuration:

  • Run the configure script and enable the plugin in the Plugins section.
  • Configure additional plugin settings in the Extensions section if needed. Settings:
    $TWiki::cfg{Plugins}{DoxygenImportPlugin}{TemplateTopic} # Name of template topic to use to generate topics. Can be Web or Web.TopicName. Default: WebTopicEditTemplate.
    $TWiki::cfg{Plugins}{WatchlistPlugin}{LogAction} # Log plugin actions. See output in data/logYYYYMM.txt
    $TWiki::cfg{Plugins}{WatchlistPlugin}{Debug} # Debug plugin. See output in data/debug.txt

2. Testing:

  • Create a TestDoxygen topic containing %DOXYGENIMPORT{navigation}% and %DOXYGENIMPORT{import}%.
  • The %DOXYGENIMPORT{import}% shows an upload & import Doxygen file form.
  • Upload a .zip file containing a set of Doxygen generated files.
  • This should generate many TestDoxygen_... topics - browse to verify.

Plugin Info

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Import Doxygen documentation into TWiki by uploading a ZIP file containing Doxygen-generated files

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2013 Wave Systems Corp.
© 2013 TWiki:Main.PeterThoeny & TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Wave Systems Corp.
Plugin Version: 2013-08-16
2013-08-16: TWikibug:Item7312: Show "please wait..." message and processing icon during import
2013-08-08: TWikibug:Item7312: Fix infinite loop issue if another plugin uses expandCommonVariables in afterSaveHandler
2013-07-30: TWikibug:Item7295: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.2
CPAN Dependencies: CPAN:Archive::Zip
Other Dependencies: none
Perl Version: 5.005
Plugin Benchmarks: GoodStyle nn%, FormattedSearch nn%, DoxygenImportPlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/DoxygenImportPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/DoxygenImportPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/DoxygenImportPluginAppraisal

Related Topics: VarDOXYGENIMPORT, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 DoxygenImportPlugin.md5 r4 r3 r2 r1 manage 0.2 K 2013-08-16 - 22:54 PeterThoeny  
Compressed Zip archivetgz DoxygenImportPlugin.tgz r4 r3 r2 r1 manage 54.9 K 2013-08-16 - 22:53 PeterThoeny  
Compressed Zip archivezip DoxygenImportPlugin.zip r4 r3 r2 r1 manage 58.8 K 2013-08-16 - 22:53 PeterThoeny  
Unknown file formatEXT DoxygenImportPlugin_installer r2 r1 manage 3.7 K 2013-08-16 - 22:54 PeterThoeny  
Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r5 - 2013-10-16 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.