Re: API Documentation Generation

On Sun, Mar 25, 2012 at 5:08 PM, Alexey Borzov <borz_off@cs.msu.su> wrote: > 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/<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/Validate_HU/docs/latest/> >> >> http://test.pear.php.net/**package/HTML_Select/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<https://github.com/pear/HTML_Select/blob/master/HTML/Select.php‹23´ÿú+{cçØk > ‹> > > Yeah I did look around further at this, but couldn't figure it out. You can see the packages generated - http://test.pear.php.net/package/HTML_Select/docs/latest/packages/ - but not listed in the index. There's https://github.com/phpDocumentor/phpDocumentor2/issues/384 https://github.com/phpDocumentor/phpDocumentor2/issues/356 and I think the thing we are seeing is https://github.com/phpDocumentor/phpDocumentor2/issues/402 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<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. > I agree that 3 is the most feasible; and would probably do that first. But I am worried about incoming links in old documentation a bit. That URI above has only links we control, which is OK https://www.google.com.au/webhp?sourceid=chrome-instant&ix=sea&ie=UTF-8&ion=1#q=link%3Ahttp%3A%2F%2Fpear.php.net%2Fpackage%2FHTML_QuickForm2%2Fdocs%2Flatest%2FHTML_QuickForm2%2FHTML_QuickForm2_Factory.html&hl=en&prmd=imvns&filter=0&bav=on.2,or.r_gc.r_pw.r_cp.r_qf.,cf.osb&fp=e53ed314101be7dc&ix=sea&ion=1&biw=1660&bih=989 ... but there must be lots of tutorials, blog posts, etc that link to specific manual pages. I wonder if we can do an error document which does: 1. You linked to a /latest/ URI, using format which looks like old style links, but got a 404 2. Redirect the user to /x.y.z/ and 1. You linked to a /x.y.z/ URI, using format which looks like old style links, but got a 404 2. Redirect user to /(x.y.z) - 1/ It's a pity there's no SELECT * FROM valid_paths or something - doing this via the filesystem/repeated redirects seems difficult.