Using Doxygen to Create Xcode Documentation Sets

Documentation sets (doc sets) provide a convenient way for an Xcode developer to search API and conceptual documentation (including guides, tutorials, TechNotes, and Q&As), sample code, and anything else provided by the doc set creator. Many developers already use Apple-provided doc sets, as shown in Figure 1.


Figure 1  Apple Doc Sets in Xcode

In Xcode 3.0, you can integrate doc sets for your own products into the Xcode Documentation window. By providing your documentation as a doc set, users can take advantage of all the Xcode documentation-viewing features to browse and search for information in your documents. In addition, the API docs provided in a doc set can be hooked up to the Research Assistant in Xcode. The Research Assistant, shown in Figure 2, follows your selection in the code editor and offers information on documented API and build settings. Clicking on a symbol brings up a summary of the documentation for that symbol and provides links to the complete documentation.


Figure 2  Research Assistant in Xcode

In this article we show how to generate the documentation, package it as a doc set, and place it in a location known to Xcode. Another option is to publish the doc set as a feed, which is an RSS-based subscription mechanism. An RSS feed is very useful for development teams of all sizes. By subscribing to the RSS feed you easily and automatically receive updates to the doc set, which Xcode will install for you.

Doc sets have a well-defined structure, as outlined in the Documentation Set Guide (see the link at the end of this article.) But the process of getting everything in the right place can be tedious if done by hand. Fortunately there is an easier alternative. Doxygen, the open source documentation generator, allows you to generate doc sets directly from your source code. It handles the HTML generation, packaging, and placement of the doc set, freeing you to focus on content.

Doxygen

Doxygen generates documentation from source code files. You can use Doxygen to create online and offline reference material in a number of different formats. Doxygen supports many popular programming languages, including C/C++, Objective-C, Java, Python, and others. In this article we use Doxygen to create a HTML doc set from an Xcode Objective-C project. A header file from the project is shown in Listing 1. Remember that the more comments you include, the more documentation Doxygen will produce!

Listing 1: DoxygenExample.h

 
//
//  DoxygenExample.h
//  DoxygenExample
//
//  Created on 1/31/08.
//  Copyright 2008 __MyCompanyName__. All rights reserved.
//
 
#import <Cocoa/Cocoa.h>
 
/**
  Sample interface
*/
@interface DoxygenExample : NSObject {
 
}
 
/**
  This method does nothing.
*/
- (void)doNothing;
 
@end

Using the Doxygen GUI

To get started with Doxygen, you first need to download a copy of the application from the web site, which is linked at the end of this article. The Doxygen home page contains a link to the Doxygen application disk image, as well as to the latest source code. The application includes an OS X graphical user interface (GUI) that provides easy access to the command-line features. The GUI is shown in Figure 3.


Figure 3  The Doxygen GUI
The Doxygen GUIThe Doxygen GUI

Conveniently, the GUI lists the steps required to generate documentation. The first step is to configure Doxygen using one of the three available options. The Wizard makes it easy to get started, but you will often want the flexibility offered by Expert mode, while Load allows you to select and use an existing configuration file. Once you have changed any settings, save the configuration file. Click the Save button and select the location and name for your configuration file. Next, specify the directory containing your source code. Finally, click the Start button to generate the documentation.

Now that you have had an introduction to running Doxygen, we turn our attention to creating a doc set.

Generating a Doc Set

You can easily generate a doc set using the Doxygen GUI. Figure 4 shows the HTML settings tab in the Expert mode configuration dialog. Many of the default settings are adequate for generating documentation, but you can customize the output in many ways. Make sure the GENERATE_HTML box is checked. In Figure 4, if you look closely you can see the doc set settings. Be sure to check GENERATE_DOCSET. Xcode will display the DOCSET_FEEDNAME value in the documentation window as the name of your doc set, so even if you are not providing an RSS feed, you should fill-in this text field with something meaningful. Use your company and product reverse-DNS name for the DOCSET_BUNDLE_ID.


Figure 4  Configuring Doxygen
Configuring DoxygenConfiguring Doxygen

Next, click the Start button shown in Figure 3. Doxygen will create the HTML documentation, along with a Makefile. When you run "make install" on this Makefile, Doxygen will package and install the HTML as a doc set that can be opened in the Xcode documentation window.

Generating Doc Sets In Xcode

There is another way to generate a doc set with Doxygen, and that is to create it as part of your project build in Xcode. To accomplish this, you can add a script as a build phase to your Xcode project. In Xcode parlance this is a "Run Script Build Phase". Figure 5 shows the menu selections needed to add this script as a build phase. In Figure 6 the new Run Script phase is highlighted under the target.


Figure 5  Add a Run Script Build Phase to an Xcode Project
Add a Run Script Build Phase to an Xcode ProjectAdd a Run Script Build Phase to an Xcode Project

Figure 6  The Run Script Build Phase
The Run Script Build PhaseThe Run Script Build Phase

Once you add it, double-clicking on the Run Script build phase displays a window in which you can write your script. Paste the script from Listing 2 into the script window. The result should look similar to Figure 7.

Listing 2: Doc Set Build Script

 
#  Build the doxygen documentation for the project and load the docset into Xcode.
 
#  Use the following to adjust the value of the $DOXYGEN_PATH User-Defined Setting:
#    Binary install location: /Applications/Doxygen.app/Contents/Resources/doxygen
#    Source build install location: /usr/local/bin/doxygen
 
#  If the config file doesn't exist, run 'doxygen -g $SOURCE_ROOT/doxygen.config' to
#   a get default file.
 
if ! [ -f $SOURCE_ROOT/doxygen.config ]
then
  echo doxygen config file does not exist
  $DOXYGEN_PATH -g $SOURCE_ROOT/doxygen.config
fi
 
#  Append the proper input/output directories and docset info to the config file.
#  This works even though values are assigned higher up in the file. Easier than sed.
 
cp $SOURCE_ROOT/doxygen.config $TEMP_DIR/doxygen.config
 
echo "INPUT = $SOURCE_ROOT" >> $TEMP_DIR/doxygen.config
echo "OUTPUT_DIRECTORY = $SOURCE_ROOT/DoxygenDocs.docset" >> $TEMP_DIR/doxygen.config
echo "GENERATE_DOCSET        = YES" >> $TEMP_DIR/doxygen.config
echo "DOCSET_BUNDLE_ID       = com.mycompany.DoxygenExample" >> $TEMP_DIR/doxygen.config
 
#  Run doxygen on the updated config file.
#  Note: doxygen creates a Makefile that does most of the heavy lifting.
 
$DOXYGEN_PATH $TEMP_DIR/doxygen.config
 
#  make will invoke docsetutil. Take a look at the Makefile to see how this is done.
 
make -C $SOURCE_ROOT/DoxygenDocs.docset/html install
 
#  Construct a temporary applescript file to tell Xcode to load a docset.
 
rm -f $TEMP_DIR/loadDocSet.scpt
 
echo "tell application \"Xcode\"" >> $TEMP_DIR/loadDocSet.scpt
echo "load documentation set with path \"/Users/$USER/Library/Developer/Shared/Documentation/DocSets/\""
     >> $TEMP_DIR/loadDocSet.scpt
echo "end tell" >> $TEMP_DIR/loadDocSet.scpt
 
#  Run the load-docset applescript command.
 
osascript $TEMP_DIR/loadDocSet.scpt
 
exit 0

Figure 7  Type or Paste the Script into the Script Phase Window
Type or Paste the Script into the Script Phase Window

You may have noticed that the script uses a variable that specifies the path to the Doxygen executable. This is necessary because the Doxygen binary, as installed from the disk image, installs in a different location than if you build from source. The respective paths are listed at the top of the script.

Figure 8 illustrates the Get Info command, which displays the target information.


Figure 8  Display the Target Info Window
Display the Product Info Window

In the Build pane, the User-Defined Settings menu lets you assign a value to an environment variable. This value can be used to control the build. Figure 9 shows how to add a setting.


Figure 9  Add a User-Defined Setting
Add a User-Defined SettingAdd a User-Defined Setting

In Figure 10, set the value for the path to the Doxygen binary.


Figure 10  Set the Doxygen Path
Set the Doxygen Path

Now build the Xcode project. When the Run Script phase executes, it should generate the doc set. If all goes well you will see build results similar to Figure 11.


Figure 11  The Build Results Window
The Build Results WindowThe Build Results Window

Doxygen is highly configurable, but we only changed a few settings to generate a doc set that Xcode can open and search. You can reuse the script in Listing 2 with minor modifications in other Xcode projects. Here are some important points regarding the script:


Figure 12  Updated Doc Set
Updated Doc SetUpdated Doc Set

Doxygen is highly configurable and can generate output in several formats. This example only generated HTML output, but you should look at the generated configuration and Makefiles to get an idea of other options. And even though everything you need to build a doc set is included in the current version of Doxygen, you may wish to experiment with the latest Doxygen source code, which is available on Sourceforge. The Doxygen web site has additional information, including download, build and installation instructions.

For More Information

Using the techniques discussed in this article, you can use Doxygen to create your own documentation sets for use in Xcode. The Apple Developer Reference Library documents listed below will help you find more specific information.