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.

--
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php