Re: API Documentation Generation

Hi Daniel, On 24.03.2012 13:32, Daniel O'Connor wrote:

Round 2, with phpdocumentor2, default skin. http://test.pear.php.net/package/SOAP/docs/latest/ I did http://test.pear.php.net/package/Validate_HU/docs/latest/ http://test.pear.php.net/package/HTML_Select/docs/latest/ but they appear to be upset - lacking a @package annotation perhaps?.

Looks rather like a bug in phpdoc2. HTML_Select at least has a @package annotation https://github.com/pear/HTML_Select/blob/master/HTML/Select.php Also class inheritance diagram works for it: http://test.pear.php.net/package/HTML_Select/docs/latest/graph_class.html

I reckon that we could merge the old pear skin Mike helped with without much trouble - basically adding a top banner with package style/links. What do people think?

I think that PEAR skin is one half of a problem. Another half is that DocBook-based documentation links to generated API docs via <phd:pearapi /> tags. E.g. I put <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Factory::createElement" /> into DocBook and I receive <a href="http://pear.php.net/package/HTML_QuickForm2/docs/latest/HTML_QuickForm2/HTML_QuickForm2_Factory.html#methodcreateElement" class="apidoclink">HTML_QuickForm2_Factory::createElement()</a> in the resultant HTML. I briefly looked and URLs in phpdoc2 are different from phpdoc. Basically we have three options: 1) Make phpdoc2 generate same URLs; 2) Server-side translation of URLs (mod_rewrite or something); 3) Make Phd_PEAR generate phpdoc2-style URLs I think 3) is the most feasible solution, but we should synchronize phpdoc and Phd_PEAR upgrades to prevent an obvious issue when links in the DocBook-based docs are different from those in API docs.