Solution: Creating eZ publish Doxygen API Documentation

« 
Previous article
|
Solution
|
Next article
 »

Table of contents:

Introduction

There is a vast amount of documentation available regarding the source code of eZ publish within the php source code comments.

This source code documentation must be generated into a format like html pages to be useful to developers.

The PubSVN server hosts several generated copies of this documentation one for each major version of eZ publish. These hosted copies of the documentation are useful for online reading.

If your interested in generating your own copy this documentation follow the following steps.

Steps

  1. Download the latest stable release of Doxygen
  2. Download the latest stable release of eZ publish
  3. Install Doxygen
  4. Run Doxygen on eZ publish
  5. Review the generated HTML API documentation

Using shell

Install

Download the latest source distribution, doxygen-1.5.1.src.tar.gz (2.8M) ( ftp | http )

# wget http://ftp.stack.nl/pub/users/dimitri/doxygen-1.5.1.src.tar.gz

Unpack package

# tar -zxf doxygen-1.5.1.src.tar.gz;

Configure package

# cd doxygen-1.5.1;
# ./configure --help;

# sudo apt-get install qt3-linguist qt3-dev-tools-embedded qt3-dev-tools-compat qt3-dev-tools qt3-apps-dev libqt3-mt-dev libqt3-headers libqt3-compat-headers;

# mkdir /usr/local/doxygen;
# ./configure --prefix /usr/local/doxygen --english-only;

Make and Install package

# make;
# make install;

Generate Documentation

# /usr/local/doxygen/bin/doxygen --help

 

# cd /web/ez/ezpublish-3.8.4/doc/

# svn export http://pubsvn.ez.no/nextgen/trunk/tests
# svn export http://pubsvn.ez.no/nextgen/trunk/benchmarks

# /usr/local/doxygen/bin/doxygen /web/ez/ezpublish-3.8.4/doc/doxygen/Doxyfile

Results

You can view an example log the result of running the doxygen documentation generation command.

Review Documentation

The resulting documentation will have been generated and stored on disk in the 'doc/generated/html/' directory.

Extending Doxygen Configuration

The default doxygen configuration file distributed with eZ publish has been pointed out to not take advantage of a few useful configuration features available. This is because the documentation can be viewed using a URL like "http://example.org/reference/view/ez" through the eZ interface. Having extra HTML and JavaScript would break this view. However, you can create a standalone version of the documentation by changing the settings below.

Note, "If the GENERATE_TREEVIEW tag is set to YES, a side panel will be generated containing a tree-like index structure...."

This option used by PubSVN's hosted copy of the generated doxygen documentation generated from eZ publish trunk. I belive by default this option is not enabled!

Removing the references to "doc/doxygen/empty.html" in the Doxyfile on lines 608 and 614 causes the Doxygen standard theme to be used (as seen on PubSVN).

Using GUI

Install

Download the latest MacOS or Windows package.

Doxygen-1.5.1.dmg (16.5M) ( ftp | http )

doxygen-1.5.1-p1-setup.exe (5.3M) ( ftp | http )

Generate Documentation

Here is the basic use of the gui documentation wizard named doxywizard. If you want to use a previously defined doxygen configuration file Doxyfile, pass it as an argument to the wizard or use the "Load" button in the main window.

(Screenshots to be provided when image upload will be available)

Click on the Wizard button, a new dialog box appears.

  • Give a name and a version to your project (eg. Ezpdoc and 1.0 respectively)
  • Give the directory name where ezpublish is installed (eg. /var/www/html/Ezpublish)
  • Check the "Scan recursively" box
  • Give the name of an existing destination directory (eg. /home/me/Ezpublish/Doxygen)

Click on the "Mode" tab

  • Check the "Documented entities only"
  • Check one of the "Optimize" that fits to your purpose

Click on the "Output" Tab

  • Check "HTML" and "with frame and a navigation tree"
  • Check "Include cross-referenced..."
  • uncheck all the others unless you need it

Click on the 3Diagrams" tab

  • Check the "Use buit-in class diagram generator"

Click the OK button of the Wizard dialog box

Click the Save button of doxywizard main screen and save it as Doxyfile in the destination directory previously entered

The final step is to click on the Start button and here you are !

Review Documentation

The resulting documentation will have been generated and stored on disk in the 'doc/generated/html/' directory.

Summary

This process can be automated to generate eZ publish documentation on a regular basis via cron.

External Reference