Using ApiGenerator to generate documentation

The release of the new API at http://api.cakephp.org wasn’t quite as smooth as I would have liked it. However, since the initial release things have constantly been improving. The search is now much more effective, and global functions are now in the index. So things are looking better each day. I hope to answer a few questions surrounding ApiGenerator today.

Why did you change it if it wasn’t broken?

This is a question that I’ve been asked a few times in the past few weeks. To be honest the old API was horribly broken. Entire classes were missing. File, and CakeSession for example were simply omitted because doxygen doesn’t properly read conditionally included files. Even classes that did exist in the API were incomplete. Model for example had no documentation for saveAll(). We were also somewhat limited in what formatting could be generated. We did look at other options like PHPDoc however the lack of a search was a deal breaker, as that seems to be one of the most often used features in the API. So the API was broken, and it needed to be fixed, and we needed a solution that worked for our needs.

Why reflection?

As I mentioned last time ApiGenerator does very little file parsing, and instead uses Reflection to generate documentation. This was another design decision. We needed to get the new API together pretty quickly. This made a file parsing strategy unfeasible. I don’t know if you’ve ever thought about how complicated the regular expressions and text processing needs to be, but I have, and it hurt my brain. PHPDoc has 20+ classes just for file parsing. Thankfully PHP has a pretty good Reflection API that affords doc block extraction. Reflection can be used to do lots of other things as well but I was most interested in documentation aspect of it. Furthermore, this all meant that I could cobble together something working in much, much less time. While reflection did give a whole bunch of advantages it has one big draw back. The code is live. In order to parse docs you need to be able to load the files. This also means that you can run into namespacing conflicts. Lastly, you can’t generate docs for old versions of the classes powering the doc extraction.

So how do I use this thing?

Well first there are a few requirements. You must have:

• PHP 5.2.3 or better. There are parts of the reflection API that didn’t exist before then.
• A database with room for 1 table. – Yes there is only one table, but its super important.
• A command line. You need access to a shell, no shell, no API. End of story.

So if you meet the requirements we can get started. As stated in the requirements, you will need to know how to use the cake console. As all the API generation / maintainance / config is all done there.

Installation.

Download / git clone the project into app/plugins/api_generator from http://github.com/cakephp/api_generator. It must go here, sprinkling the files throughout your app, or calling the directory teh_api will not work. Next open up your console and run

cake api_index initdb

This will install the database table. You will be asked a few questions about the schema you are installing, so say yes to dropping and adding the tables. Next up is getting a configuration file.

Configuration

ApiGenerator uses an INI file for its configuration. This file can be written by hand or generated with the console. To generate the configuration run:

cake api_index showfiles

The shell will notice that you don’t have a config file and prompt you to make one.

Is the first prompt, your path will look different, but enter the path to the code base to be documented. It will ask about multiple paths, but they are not fully implemented at this point in time.

Next up you have to setup exclusions. Exclusions tell ApiGenerator things it should keep hidden. You can set exclusions based on the visibility of methods & properties.

Next you should include a list of directory names that are not to be looked in. I use tests, locale, config, webroot, tmp for my apps. This is just a list of directory names and not path fragments.

Next is a list of file names to exclude. These files will not be included in the documentation. I use index.php, empty in my app.

Extensions of files to look at, and file name pattern to use. Pretty simple. The defaults work pretty well.

This is the most complicated part of the configuration. Because ApiGenerator relies on reflection, it needs all parent classes loaded for before it can load and introspect on a class. Its pretty good at finding things once it has an index built but in order to get there, you need to map out some files that it has trouble finding. If you miss a file its ok, it will skip files it knows it doesn’t have all the parents for. You answer the above question with a class name, for example XmlHelper.

Is the next question. You now need to provide a file path to the mapped class. It can be relative to the codebase path, or an absolute path. You can add as many mappings as you wish at this time.

There you go, you now have a complete config file. You might need to tweak it as you generate the index.

Generating your first index.

The index in ApiGenerator, holds information about the methods, properties and locations of classes and functions. You can preview an index generation with

This will show the files that your index will contain based on the exclusions. Once you are satisfied with the list of files being included you can generate the index with

This will clear any existing index and repopulate the index table. Watch for errors saying files couldn’t be found with the mappings, and then add these files to your config’s mappings. Once you have a complete index, you can start exploring and viewing your API. That’s all there really is to it at this time. If you are interested in helping improve ApiGenerator, please open tickets and submit patches. I hope you find this tool useful in documenting your applications.