Re: API Documentation Generation

Hi Daniel, On 26.03.2012 3:28, Daniel O'Connor wrote:

    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 <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/

Maybe just display a 404 page talking about phpdocumentor upgrade? I doubt user will appreciate being redirected to something other than docs for the *latest* release.

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/

I am not sure I understand this part. We'll probably keep old generated docs and only generate new ones for the latest release of the package (so that /latest/ URI and consequently PhD links will work)? I don't see how these links can appear then.

It's a pity there's no SELECT * FROM valid_paths or something - doing this via the filesystem/repeated redirects seems difficult.

Yep, so I'd not bother too much.