Xcode Pages

The XcodePages gem helps you publish documentation from within Xcode using Doxygen. On Mountain Lion, prerequisites include Doxygen 1.8.2 or above and optionally GraphViz 2.28.0 stable release or above. Drag the Doxygen application to /Applications as normal. Double-click the GraphViz package to install it.

The term 'Pages' comes from the ultimate goal: to publish the HTML web pages on the Internet somewhere appropriate, e.g. on GitHub via the gh-pages branch feature.

The gem works for Objective-C projects built using Apple's Xcode IDE. It consequently focuses on documentation within Objective-C and Objective-C++ source files; files ending with extensions h, m or mm.

How to Use Xcode Pages

Step 1

Add a new target to your Xcode project. Suppose your Xcode project has the name MyProject. Add a new External Build System target called MyProjectPages.

Step 2

Set the external build target up as follows.

  • Build Tool: /bin/sh
  • Arguments: -c "$HOME/.rvm/bin/rvm-auto-ruby -r XcodePages -e XcodePages.doxygen_docset_install"
  • Directory: None
  • Pass build setting in environment: Yes

Note that the arguments above tell the shell to run $HOME/.rvm/bin/rvm-auto-ruby. This assumes you are running RVM.

Also, do not try to promote your Ruby path to the Build Tool setting unless you have a fixed path to Ruby, e.g. /usr/bin/ruby. Xcode does not make environment variables substitutions within the Build Tool setting.

Build Settings

Leave Build Settings and Phases as defaults, that is, unless you need to override your PATH to add some non-standard executable locations. For instance, if you install Doxygen.app using the OS X disk image rather than installing Doxygen using MacPorts and such, then the doxygen binary lives at /Applications/Doxygen.app/Contents/Resources. You will need to add that path element to your Unix PATH environment variable. Similarly, if you install Graphviz from some package and it lives at another unusual location, you will need to add that too. Best place for adding this for Xcode is within Build Settings. Note, Xcode's sub-processes do not pick up your Bash profile, so setting these search paths up for your user account will not work. Instead, add a setting like this to your Pages build target.

PATH = /bin:/usr/bin:/usr/local/bin:/Applications/Doxygen.app/Contents/Resources:/usr/local/graphviz-2.14/bin

Step 3

Set up a new Doxyfile in your project's source root containing four Doxygen settings:

  • GENERATE_DOCSET = YES
  • DOCSET_FEEDNAME = "My Project Documentation Set"
  • DOCSET_BUNDLE_ID = com.domain.MyProjectDocSet
  • DOCSET_PUBLISHER_ID = com.domain.MyProjectDocSet.documentation
  • DOCSET_PUBLISHER_NAME = My Publisher Name

DOCSET_BUNDLE_ID is the most significant item for this determines the base name for the documentation set. Doxygen just adds extension docset to make the file name.

Please Note

Be aware that if you specify a Doxyfile in the project source root folder, any settings provided therein override XcodePages defaults. This may include the INPUT setting and OUTPUT_DIRECTORY. Even a blank value overrides the default. You need to comment out or delete the setting to allow XcodePages to auto-generate the appropriate default.

When Pushing to GitHub Pages

When your project uses GitHub for version control, you can conveniently publish the HTML documentation pages by pushing the HTML to branch gh-pages. However, is a caveat when doing this.

You will need to touch and commit .nojekyll in the root of your branch. Otherwise, the Doxygen pages will not appear. GitHub uses Jekyll, a blog-aware static site generator that monkeys around with underscores within paths. Unfortunately, Doxygen uses underscore in path names as delimiters, by default. You can switch this off with .nojekyll or tell Doxygen to use short names using SHORT_NAMES = YES in your Doxyfile.

In addition, you might want to add some patterns for Git to ignore to your .gitignore for the gh-pages branch. The following patterns match Doxygen's build cruft and the docset bundle. No need to commit them to GitHub.

  • *.map
  • *.md5
  • Info.plist
  • Makefile
  • Nodes.xml
  • Tokens.xml
  • *.docset/

Step 4

You can now switch target to MyProjectPages and hit Build (Cmd+B) to compile the documentation. It will appear in folder MyProjectPages within the source root folder and a new Xcode docset will appear in ~/Library/Developer/Shared/Documentation/DocSets.

You would normally have to reload Xcode to see the new documentation. As a courtesy, the last step tells the running Xcode application to pick up the new set.

Benefits

  • Takes the "fiddle" out of fiddling with Doxygen.

    There is naturally more documentation, and better too, when generating the documentation is easy. Would it not be easy if you could just type some Doxygen comment blocks in Xcode, press Cmd+B to build the documentation and then immediately read it within Xcode's documentation? Try out XcodePages! It is that easy.

  • You can easily identify undocumented classes and methods.

    Warning messages output by Doxygen make this possible. After building your project Pages target, the build results contain warning about undocumented elements within your project. Press the Cmd+' (Jump to Next Issue command) to navigate through the undocumented code.

    Note, however, that you may still need to reload (or even restart Xcode) if your major documentation sections change. Xcode document viewer appears to cache them.

Examples

You can find examples of projects using XcodePages here:

Prerequisites

  • Xcode and associated Apple developer tools
  • Ruby and RubyGems package manager
  • Doxygen