search

pear2 / pear2.php.net

PEAR2 website
http://pear2.php.net/
Other
19 stars 9 forks source link

Add API Documentation #5

Open mfonda opened 13 years ago

mfonda commented 13 years ago

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

helgi commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

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:

@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 commented 13 years ago

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 commented 13 years ago

@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 commented 13 years ago

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 commented 13 years ago

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 commented 13 years ago

@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 commented 13 years ago

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

mvriel commented 12 years ago

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?