Building API Docs
This is a description of the steps to take to build the API documentation. The API docs should be available online (generator or runtime), but there may be cases where you wish to build a local copy. (Note that this example combines docs for the generator classes and the runtime classes.) Or you may just want to see an example of how to do this using PhpDocumentor for your own projects.
Install PhpDocumentor
You his part is extremely easy. Note that you need 1.3.x if you want to build API docs for a PHP5 project.
1. You may need to indicate to PEAR that you would like to be able to install unstable packages. At time of writing the 1.3 version of PhpDocumentor is 1.3.0RC3 (which is 'beta' state for PEAR).
$> pear config-set preferred_state beta
2. Install PhpDocumentor
$> pear install PhpDocumentor
You may also wish to install XML_Beautifier (which also has some other dependencies). It's an "optional" dependency -- who knows what it does! -- but with a name like that, you couldn't go wrong. :)
Setup a Config File
PhpDocumentor can use config files so you don't have to enter everything on the commandline. These files need to be stored in the user/ subdirectory of the PhpDocumentor data directory. On my Gentoo system the data directory is located at /usr/lib/php/data/PhpDocumentor.
Here's my Propel config file, which I've named propel.ini in that user/ subdirectory.
[Parse Data] title = Propel API ;; parse files that start with a . like .bash_profile hidden = false ;; show elements marked @access private in documentation by setting this to on parseprivate = off ;; parse with javadoc-like description (first sentence is always the short description) javadocdesc = off defaultpackagename = propel ;; output any parsing information? set to 'on' for cron jobs ;quiet = on ;; where should the documentation be written? ;; legal values: a legal path target = /var/www/propel.phpdb.org/htdocs/docs/api/current/ ;; Which files should be parsed out as special documentation files, such as README, ;; INSTALL and CHANGELOG? This overrides the default files found in ;; phpDocumentor.ini (this file is not a user .ini file, but the global file) readmeinstallchangelog = README, INSTALL, CHANGELOG, NEWS, FAQ, LICENSE ;; limit output to the specified packages, even if others are parsed ;; legal values: package names separated by commas ;packageoutput = package1,package2 ;; comma-separated list of directories to parse directory = /opt/propel/trunk/runtime/classes,/opt/propel/trunk/generator/classes ;; comma-separated list of files, directories or wildcards ? and * (any wildcard) to ignore ignore = templates_c/,*HTML/default/*,spec/ ;; comma-separated list of Converters to use in outputformat:Convertername:templatedirectory format ;; legal values: HTML:frames:default,HTML:frames:l0l33t,HTML:frames:phpdoc.de,HTML:frames:phphtmllib, ;; HTML:frames:earthli, ;; HTML:frames:DOM/default,HTML:frames:DOM/l0l33t,HTML:frames:DOM/phpdoc.de, ;; HTML:frames:DOM/phphtmllib,HTML:frames:DOM/earthli ;; HTML:Smarty:default,HTML:Smarty:PHP,HTML:Smarty:HandS ;; PDF:default:default,CHM:default:default,XML:DocBook/peardoc2:default output=HTML:Smarty:PHP ;; turn this option on if you want highlighted source code for every file ;; legal values: on/off sourcecode = on
Run phpdoc
Finally, you can run the phpdoc script (which should be on your path), specifying the config file we created above.
$> phpdoc -c propel.ini
