[#6131] API calls definitions automatically rendered as wiki pages
Summary API calls definitions automatically rendered as wiki pages
Queue Wicked
Type Enhancement
State Accepted
Priority 1. Low
Owners chuck@horde.org, jan@horde.org
Requester duck@obala.net
Created 2008-01-21 (4584 days ago)
Due
Updated 2009-02-22 (4186 days ago)
Assigned 2008-02-14 (4560 days ago)
Resolved
Milestone
Patch No

Comments
Duck <duck@obala.net> 2008-01-21 22:31:02
A set of batch script using PHP5 Reflection API to render horde 
modules API documentation in HTML or WIKI format. Using together with 
#6130 patch (also included) you can easy update/create wiki pages with 
API call descriptions.

Duck <duck@obala.net> 2008-01-21 22:33:38
Rendered page example.

Jan Schneider <jan@horde.org> 2008-01-23 15:38:31
This looks really nice! I wonder how/where we should integrate this 
though. And you probably need to update it because I changed the API 
methods a bit. The CSS links are no longer returned by the display 
method.

Duck <duck@obala.net> 2008-01-24 15:29:38
> This looks really nice! I wonder how/where we should integrate this

> though.



I found it useful for outside partners not needing to look at the code 
or browse around for docs as they can find it on our partner pages. So 
I think it can be done the same here. Add them in the already existing 
crontab documentation update to update Horde Wiki pages or/and add 
them on the webpages as "External methods" in the documentation 
section (something like http://www.horde.org/imp/docs/?f=api.html)

Duck <duck@obala.net> 2008-01-31 11:37:38
- Handle multiple parameter types.

- Avoid warnings with no documentation.

- Tell if method has missing documentation.

Jan Schneider <jan@horde.org> 2008-02-15 13:18:59
I added the Horde_Document classes as a Horde_Relection package to the 
framework, including proper credits to Sergio Carvalho and a few 
coding style tweaks. The Wiki driver should still be changed to *not* 
mess with the method names. I see why this is necessary for the 
(external) API documentation, but it doesn't help if this should 
become a general purpose package. Instead, a subclass could hook into 
the method name processing.



I changed my mind and would like to see this script added to 
wicked/scripts/. By default, it could be run in any Horde installation 
to autogenerate API docs of the currently installed Horde apps.



I would like it to generate the following wiki page structure. The 
prefix should be editable in the script header, so that we would 
create everything below /Doc/Dev/Apis/, a sane default might be 
/HordeApis/:



Apis (or HordeApis) - contains the instructions how to call the api 
methods. The RPC package has more example that have just been added by 
Chuck. Additionally in contains a list to all application sub-pages, 
e.g.:

Apis/KronolithApi - contains a list of versions. The idea is to allow 
to keep track of different application versions. Thus the script 
should not rewrite this page completely, but only add new versions as 
it detects them.

Apis/KronolithApi/2.2-cvs - contains the actual API docs. This could 
safely be overwritten. If run on a stable version, it won't change 
anyway, and if run on a cvs version, it properly updates the docs.



Duck <duck@obala.net> 2008-02-15 15:25:01
A wiki script with Horde_Reflection from framework. Allows to specify 
the page prefix and to add or not the api version to pagename. Of 
course you should change it to swit your wishes.

Chuck Hagenbuch <chuck@horde.org> 2008-02-17 23:25:04
> A wiki script with Horde_Reflection from framework.



It'd be great if this used Horde_Argv instead of Console_Getopt :)

Chuck Hagenbuch <chuck@horde.org> 2008-02-17 23:26:06
Sounds like we should move this back to the Wicked queue.

Chuck Hagenbuch <chuck@horde.org> 2008-04-25 04:08:18
With Horde_Reflection in CVS, does the api.php script replace 
everything in explain.tgz?

Duck <duck@obala.net> 2008-05-05 12:14:59
> With Horde_Reflection in CVS, does the api.php script replace

> everything in explain.tgz?



Not really. But uses Horde_Reflection instead of its own class and is 
more configurable.

Duck <duck@obala.net> 2008-05-05 12:18:32
A updated version of collection.php script from explan.tgz. Create 
documentation even for apis without "provides" configured in registry 
and notify that this methods can be called only locally with 
callByPackage().

Duck <duck@obala.net> 2008-10-31 15:06:57
- Use commited framework classes (Horde_Reflection)

- Added command line script to use CLI implemtation (see bug #6278)



All other attaches can be deleted.

Duck <duck@obala.net> 2008-10-31 15:08:42
Command line screen shoot.

Duck <duck@obala.net> 2009-02-17 19:27:50
- Rename Horde_Reflection to Horde_Reflection_Parse to reflects its purpose

- Moved render subclasses in templates (next step is to move them a 
Horde_View)

- Clean up templates and removed CSS, use horde instead

- Added online on the fly documentation documentation renderer

- Allow command line script to render pages in any format

- Added Form renderer (creates a form from method parameters)

- Show example output results from from api calls (results in php, 
json, xml format) like on developers corner of facebook (still need to 
finish parameter handler)

Duck <duck@obala.net> 2009-02-17 19:29:04
The last code structured like an application for a cleaner preview.

Duck <duck@obala.net> 2009-02-17 19:34:12
A screenshoot of a api call example. List my Genie (wishlist) items 
and returning them as an XMLRPC response.



I forgot to mention that now renders even if a parameter is 
optional/required or not.

Duck <duck@obala.net> 2009-02-22 13:05:28
- Use Horde_Argv instead Console_Opt

- Show default values of parameters if available

- Add Test template to tell us if a documentation is missing and if a 
function with default values produces warnings - it must not.