Sandbox

This is needed....Joomla! API Specification in PDF
for 1.0 series and 1.5 series.

if there isn't one, i can probably generate one since i downloaded the full API in html. its something anyone can do.
however, it is just raw, no helpful text introducing it and guides along the way inside the classes and elements.

i am comparing J!API against JAVA, HTML, CSS and PHP documentation which are all easy to use as they contain useful examples.
especially the PHP.

so i would like to know if there is an ongoing effort on this, where i could take even a half cooked document, and if there isn't, then it would be a great thing to do. i know there is a wiki, but a wiki is a wiki, one can't really download a wiki.

this API Specification PDF Document would be a working copy for all to use, and this is a basic requirement. It is only after this that it makes sense to do a flowchart or some sort of flow diagram for joomla.

as said, i have the 1.5 API but not the 1.0 API. that is also essential i think, as it is the starting point. even they are not available, it is quite possible to develop one.

so i am looking for this document with *plenty* of examples for it to be useful and at par with the others. thanks much.

PDF is the only one missing from here:
http://dev.joomla.org/content/view/16/59/

I would prefer PDF as well.

A lot of the folks in J101 are using the eclipse IDE, it has a neat project tool that allows you to list all of the built in functions and classes
No need for a pdf, the code is right there in your developing environment.

You have stated you dont want to participate in the skype chats, well that is where people are doing what you ask. helping each other and working on resources together.

Email is your preferred method so while that might work it is not very collaborative.

There is a tutorial on the wiki that tells you how to install phpeclipse. Give it a try.

Thanks, I'll give eclipse a try.

jalil wrote:This is needed....Joomla! API Specification in PDF
for 1.0 series and 1.5 series.

if there isn't one, i can probably generate one since i downloaded the full API in html. its something anyone can do.
however, it is just raw, no helpful text introducing it and guides along the way inside the classes and elements.

i am comparing J!API against JAVA, HTML, CSS and PHP documentation which are all easy to use as they contain useful examples.
especially the PHP.

so i would like to know if there is an ongoing effort on this, where i could take even a half cooked document, and if there isn't, then it would be a great thing to do. i know there is a wiki, but a wiki is a wiki, one can't really download a wiki.

this API Specification PDF Document would be a working copy for all to use, and this is a basic requirement. It is only after this that it makes sense to do a flowchart or some sort of flow diagram for joomla.

as said, i have the 1.5 API but not the 1.0 API. that is also essential i think, as it is the starting point. even they are not available, it is quite possible to develop one.

so i am looking for this document with *plenty* of examples for it to be useful and at par with the others. thanks much.

Wow!  A lot of questions there!

Let's start with 1.0.  We simply don't have the resources to do any more documentation on the 1.0 series.  It would also be much more difficult to achieve as the phpDoc tags in the code are almost non-existent and in some cases downright wrong.  Our efforts are now devoted exclusively to 1.5.

So, onto 1.5.  The Framework API is (partially) documented on the developer wiki.  This is produced "by hand" and one of our principal goals was to have one or more examples of how to use each method and class in the API.  We're still some way off achieving that goal; we need more volunteers to help us finish it.

We also have the automatically generated API documentation at http://api.joomla.org/.  This has been made possible by the considerable effort that the developers have put into making sure that most of the methods and classes in the API have at least a minimal set of phpDoc tags.  The whole api.joomla.org site is generated using the phpDocumentor tool and since it's open source, you can download and run it against the Joomla! codebase yourself if you wish.  The custom converter and template that was used is also in the Joomla! project SVN repository.

Now phpDocumentor can be used to generate the documentation in a variety of formats, including PDF and CHM.  If someone wants to put the effort into using phpDocumentor to generate these formats then please go ahead.  I can't generate CHM myself as I no longer use Windows and the PDF code appears to be PHP4 only which makes it difficult for me as I only have PHP5 running at the moment.

Your comparison with Java, HTML, etc. is something we are aware of, but bear in mind that these are much larger projects, that have been around longer than we have and in some cases have paid staff working on the documentation.  Everything we do relies on the generosity of a small number of volunteers.

It is not entirely true that you cannot download a wiki.  In fact the entire developer wiki is held in the same SVN repository that the Joomla! codebase itself uses (just look at the documentation branch).  So anyone can download it.  You can also setup your own DocuWiki and load it up with the developer wiki pages.  In theory it should also be possible to write some code to generate PDF from the wiki data.

We are also currently researching moving the documentation over to MediaWiki which has better tool support for importing and exporting data.  I haven't tried it yet, but there is a PDF export extension available.  We can also export the data in XML and use other tools to generate PDF, CHM, whatever else we might want.  So there's lots of possibilities and lots happening.  You can either wait for it to come or help us make it happen faster.

Regards,
Chris.

thanks much. very accurate picture, so i'm able to digest it well. here's my feedback...

>Let's start with 1.0.  We simply don't have the resources to do any more documentation on the 1.0 series.

ok, it is good that you are clear about this. i will consider doing this, as 1.0 series will be like what a vintage mobile is today in my opinion.

> It would also be much more difficult to achieve as the phpDoc tags in the code are almost non-existent and in some cases downright wrong.  >Our efforts are now devoted exclusively to 1.5.

understand. i am not familiar with phpDoc at all, but would go about this in a traditional and very manual basis. it is important for me personally to understand 1.0 before trying to understand 1.5, so i have personal interest in this. basically anything i do will be made available to the community, and will be sent to joomla.org first for study or editing.

>So, onto 1.5.  The Framework API is (partially) documented on the developer wiki.  This is produced "by hand" and one of our principal goals >was to have one or more examples of how to use each method and class in the API.  We're still some way off achieving that goal; we need >more volunteers to help us finish it.

unfortunately not qualified to help with this otherwise i would gladly help. if you want a user perspective, then i'm ok with that. let me know if my hand is needed.

>We also have the automatically generated API documentation at http://api.joomla.org/.  This has been made >possible by the considerable effort that the developers have put into making sure that most of the methods and classes in the API have at least >a minimal set of phpDoc tags.  The whole api.joomla.org site is generated using the phpDocumentor tool and since it's open source, you can >download and run it against the Joomla! codebase yourself if you wish.  The custom converter and template that was used is also in the >Joomla! project SVN repository.

>Now phpDocumentor can be used to generate the documentation in a variety of formats, including PDF and CHM.  If someone wants to put >the effort into using phpDocumentor to generate these formats then please go ahead.  I can't generate CHM myself as I no longer use >Windows and the PDF code appears to be PHP4 only which makes it difficult for me as I only have PHP5 running at the moment.

i simply don't know how to use these tools, and also i'm not too big a fan of complete automation. but knowing these tools are available, then it is the source that is more important, since the phpDoc tool sounds like it's ready to produce heavy duty output. so something not to worry about then, since if the source is well sorted, i suppose anyone could just do a few clicks to generate the required format.

>Your comparison with Java, HTML, etc. is something we are aware of, but bear in mind that these are much larger projects, that have been >around longer than we have and in some cases have paid staff working on the documentation.  Everything we do relies on the generosity of a >small number of volunteers.

Yes, understood. The comparison isn't for gauging, it is for benchmarking. It is simply a reference. In fact, i am not even suggesting that that should be the way to go. Some creative being may have even better ideas for documentation, so not to worry about the others, just to note the reasons why it is useful. But you already know that. It is me who do not know that these things are in the making, which is why i had to ask.

>It is not entirely true that you cannot download a wiki.  In fact the entire developer wiki is held in the same SVN repository that the Joomla! >codebase itself uses (just look at the documentation branch).  So anyone can download it.  You can also setup your own DocuWiki and load it >up with the developer wiki pages.  In theory it should also be possible to write some code to generate PDF from the wiki data.

Ah, that is great. I was under the impression that we are not allowed to download the whole wiki, but your answer is clear that it is fine to do so. This would be good for a DIY document processing. And maybe this is one answer to your resource constraints.

>We are also currently researching moving the documentation over to MediaWiki which has better tool support for importing and exporting >data.  I haven't tried it yet, but there is a PDF export extension available.  We can also export the data in XML and use other tools to generate >PDF, CHM, whatever else we might want.  So there's lots of possibilities and lots happening.  You can either wait for it to come or help us make >it happen faster.

I'd like to wait for Joomla Code stability. RC2 is out now, and that quite fast. So i guess i have to look lower down the tree for more stable branches, and look at documents at that level, and pray that it does not change.

Thanks much for your professional response. I hope others reading and capable of offering a hand please do. I will do what i can on my part.
Ta.