The Drupal commenting standard is based on a subset of the commands in Doxygen. This is what the Drupal API site parses to create its documentation. That means documentation sites can be built for Drupal using Doxygen itself quickly and easily. And, to make it even faster I created a project with almost everything needed to create the documentation in minutes.Why Use Doxygen Instead Of The API Module?
If someone wants to create API documentation they often use the Drupal API Module. This is what powers the Drupal API and it can be used to build documentation sites for custom Drupal sites and modules. Using the API module is great. But, there are two reasons I prefer using Doxygen to build the documentation.- You don't have to deal with security upgrades. The documentation generated by Doxygen in the configurations I use is html, JavaScript (for search), and images. There are no databases or PHP processing (unless you choose to enable the PHP search engine). This is less of a maintenance burden which is nice.
- Doxygen is faster to setup. Documentation sites are useful but not all that much fun to create. They are necessity and useful but not an end goal most of us are charging for. Using the API module you are building a Drupal site and then installing the API documentation within it. Doxygen, if you have the configuration handy, can build the documentation site in seconds.
Building The Documentation Sites
Building a Documentation site takes just seconds if you have a Doxygen configuration file and there are three ways you can get one of those. The first two are to use a wizard to create your own or write one from scratch. I found that using the wizard there were still some settings I wanted to tweak on my own. And, writing one from scratch is borderline crazy.Because I found myself just copying my Doxygen config file for a project and tweaking it I created the Drupal Doxygen Base project on Github to hold the config file, any additional files that may be needed, and brief instructions on how to take this plus a site or module and have a documentation site created in minutes.
See Doxygen In Action
If you want to see a Doxygen site in action checkout the Drupal 6 API built to show Doxygen in action. This is Drupal 6, plus the API documentation (included in core as of Drupal 7 but separate before then), and the examples module.If you want the code for how this site was built see the Drupal 6 Doxygen project on Github.