Introduction

I developed some resources for generating a Xcode 3.1 documentation set from a Javadoc. Before continuing with this guide, I recommend first becoming familiar with Apple’s discussion on the topic and keeping that reference handy.

The resources I developed are quite general and should work with any Javadoc that has a valid index-all.html file. Note that some Javadoc directories contain an index-files subdirectory instead of an index-all.html file. These resources might be modified to work with index-files, but I have not tested them in this way.

I’ve used these resources to generate a Documentation Set Feed which I posted for the XAL project. In the configuration description below, I have provided example files that I’ve used for this project, and you can download and modify them as necessary for your project.

Initial Configuration

1. 1.Download and install Apple’s Xcode 3.1 developer tools.
   

2. 2.First generate or obtain your Javadoc which has an index-all.html file. Note that the HTML must be valid (no unclosed tags). You might want to inspect the DOM tree using WebKit or another tool to validate it.
   

3. 3.Create a folder (which we will refer to as the base directory) in which to place resources for building the documentation set.
   

4. 4.In the base directory, create the documentation set bundle (a folder with the file extension of docset).
   

5. 5.Open this documentation set bundle in Finder using the Show Package Contents contextual menu item.
   

6. 6.Download this Info.plist file and place it at the top level within the documentation set bundle. You will need to edit (using Property List Editor) the values in this sample file to match the information for your project. In particular, only the Bundle Version should be left the same.
   

7. 7.Inside of the documentation set bundle, create a Resources folder.
   

8. 8.Download this Nodes.xml file and place it in the Resources folder. This file describes the resources for your documentation. The sample file included here can be used unmodified unless you have additional documentation resources.
   

9. 9.Inside of the Resources folder, create a Documents folder.
   

10. 10.If your javadoc contains a single index file, download this javadocset.xsl transform file and place it in the base directory. This is an XSLT file which parses a cleaned version of the index-all.html file and generates the Tokens.xml file. However, if your javadoc contains multiple index files (as is the case for the Java JDK documentation) then you need to use this javadocsetm.xsl transform instead.
    

11. 11.If your javadoc contains a single index file, download this make-docset.command script, place it in the base directory and make sure the executable flag is set using chmod if necessary. However, if your javadoc contains multiple index files (as is the case for the Java JDK documentation) then you need to download and use this make-docsetm.command script file instead.
    You will want to edit this script to match your project and directory structure. In particular you need to edit the values of the following four variables: xcode_path, javadoc_path, doc_bundle, archive_name. The xcode_path specifies the location of the Xcode installation. The javadoc_path specifies the location of your original javadoc documentation. The doc_bundle specifies the location of the document set bundle relative to the base directory. The archive_name specifies the name of the docset archive file that will be generated.
    Note that you can comment out the archive step in the script if you only need to use the documentation set locally. Archiving is only needed if you wish to post the documentation set online to a RSS feed.
    

12. 12.If you wish to post the documentation set online to a RSS feed, download this xal-docset.atom file and place it in the base directory. You will need to edit this file to match the website where you will post the feed and the date of the update.
    

Generation

1. 1.Using Finder, navigate to the base directory folder you created in the configuration above.
   

2. 2.Execute the script by double clicking on the script: make-docset(m).command
   

Local Distribution

If you only need to use the documentation set locally, simply copy the documentation set bundle to one of the locations which Xcode searches for them such as: /Library/Developer/Shared/Documentation/DocSets

Online Distribution

Copy the atom feed file along with the documentation set archive to your website.

Updating Online Distribution

1. 1.Edit the Info.plist file inside of the documentation set bundle and change the Bundle Version to indicate that a new version of your documentation exists
   

2. 2.Edit the atom feed file to specify the current date (two places in the file) and update the version number
   

3. 3.Follow the instructions above to generate a new documentation archive
   

4. 4.Follow the instructions above for online distribution
   

Subscribing to Online Documentation

In the Xcode documentation window, select “New Subscription” and enter the feed URL. Note that I have to perform this twice. For some reason, the first time I perform this step, I only get the name of the documentation set. The second time I subscribe to the feed, I get the actual documentation.

Generating a docset for a Java JDK

1. 1.Be sure to download and configure the resources for Java Docs with multiple index files since that is what the Java JDK uses.
   

2. 2.Unjar the latest docs.jar file for the desired JDK and place the api folder inside the docset bundle's Documents folder
   

3. 3.Run the make-docsetm.command to generate documentation set