## Installation
Download / git clone the project into ```app/plugins/api_generator``` from http://thechaw.com/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.
<pre><code>
----------------------------------
api_config.ini could not be located.
Answer some questions to build it.
----------------------------------
Enter the path to the codebase.
[/Users/markstory/Sites/cake_api_gen] >
</code></pre>
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.
<pre><code>
----------------------------------
Setup some excludes
excludes remove files, folders, properties and methods from the index.
Input a comma separated list for multiple options
to continue, just answer "n"
----------------------------------
Exclude properties of the following types (private, protected, static)
[private] >
Exclude methods of the following types (private, protected, static)
[private] >
</code></pre>
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.
{{{
Comma separated list of directories to exclude
[n] >
}}}
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.
{{{
Comma separated list of files to exclude
[n] >
}}}
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.
<pre><code>
----------------------------------------
About the files in your codebase
input a comma separated list for multiple options
to continue, just answer "n"
----------------------------------------
Extensions to parse (php, ctp, tpl)
[php] >
Regex for matching files
[[a-z_\-0-9]+] >
</code></pre>
Extensions of files to look at, and file name pattern to use. Pretty simple. The defaults work pretty well.
<pre><code>
----------------------------------------------
Do you have some classes that do not map to a filename?
to continue, just answer "n"
----------------------------------------------
Class to map
[n] >
</code></pre>
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```.
{{{
Enter the path to the file that holds XmlHelper. this can be relative to the default path,
or add a / in front to use an absolute path
[/Users/markstory/Sites/cake_api_gen] >
}}}
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
{{{cake api_index showfiles}}}
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
{{{ cake api_index update }}}
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.
