Add API Documentation

[mfonda]

It would be great to add [auto-generated] API documentation for packages. This could be done using DocBlox (https://github.com/mvriel/docblox).

[helgi]

The guy behind DocBlox made up a demo theme for pear: http://demo.docblox-project.org/pear/

It's easy to theme, we could do a pear2 version pretty easily from what I can tell.

[mvriel]

I'm that guy and creating a theme is rather easy (depending upon the level of customization ;)). If it is branding that you want then it is dead simple.

I am available to help in creating a theme for PEAR2; let me know if you'd like me to assist with this.

[saltybeagle]

I think this feature is important enough that it should be inside PEAR2_SimpleChannelFrontend, but I'm not sure of the best way to integrate it.

A couple thoughts:

• write a script to scan the pear channel and generate the docs for all releases
• use DocBlox API to generate the docs on request

@mvriel Is there an API we can use or some way to pass a .tgz file to generate docs for, or do we have to extract them first?

[helgi]

I disagree that is should be in the simple channel frontend, defeats the whole point of "simple" and being a frontend for the channel server. As a plugin, sure. my 2 cents

[saltybeagle]

@helgi You're assuming docblox and API documentation can't be integrated 'simply' :-) If it can't, of course we should leave it out.

[helgi]

It is a whole new dependency or distributed with the package, it would increase the size that much more. I feel like it's more of an optional thing to be honest.

[saltybeagle]

When bundled in the .phar it's not that big of deal, Pyrus is bundled of course.

So do you think it should be completely static files generated when a release is made? I'm fine with that too, but as maintainer of a few PEAR channels, I'd love to have easily integrated API docs.

[mvriel]

@saltybeagle currently DocBlox does not support archives as sources (though that would be a cool addition!); there is however a programmatic API in addition to the command line task runner.

I get the feeling that you consider to integrate DocBlox to generate the documentation on-the-fly; if so, I can not recommend that.

Even with the speed improvements the execution still takes at least 1 or 2 seconds for a small project up to a few minutes for a larger project. (to give an impression: DocBlox takes 14 seconds to create it's own documentation from scratch and 4 seconds when parsing incrementally).

Additionally, bundling might not work out well; not only due the size (which is not that big if you leave out the PDF generation binary) but also because DocBlox updates regularly (at least once a month) and I do not know how often PEAR2_SimpleChannelFrontend is being packaged.

[mvriel]

Update: As of version 0.12.0 DocBlox supports documenting phar archives directly

[mvriel]

DocBlox is already capable of parsing the contents of a tgz file using a little trick:

By running the command: 'docblox -d phar:///my_archive.tgz'; since phar files are basically executable tgz's they can be read using the phar streamwrapper.

When testing it out I noticed that currently there is a bug with the interpretation of a phar; just fixed this and it will be possible again starting with 0.16.0.

On Mon, 2011-06-13 at 19:28 -0700, saltybeagle wrote:

I think this feature is important enough that it should be inside PEAR2_SimpleChannelFrontend, but I'm not sure of the best way to integrate it.

A couple thoughts:

• write a script to scan the pear channel and generate the docs for all releases
• use DocBlox API to generate the docs on request

@mvriel Is there an API we can use or some way to pass a .tgz file to generate docs for, or do we have to extract them first?