I've pushed a first version of a RingoJS JavaScript app to the Git repository, which will serve as a base for the LZX documentation tool, I'm building as part of the KamiJS project: https://github.com/kamiJS/lzxdoctool/blob/master/lzxdoc.js
I can already parse the LZX files of the demo applications for a list of all LZX files which belong to the application, generating an array with path information for each LZX file, and a marker showing if it's an LPS component LZX file or a custom LZX file. Running ringo lzxdoc.js -h gives you the options: > ringo:lzxdoctool raju$ ringo lzxdoc.js -h Please specify your applications main LZX file using the -a option, e.g. '-a > main.lzx' Available options: -a --app lzxfile The main LZX file of the application -v --verbose Turn verbose logging on -h --help Show this help message Example list of files generated for LzPix: ringo ~/src/git/kamijs/lzxdoctool/lzxdoc.js -a app.lzx List of LZX files for this app: 1: app.lzx 2: views/details.lzx 3: classes/albumlayout.lzx 4: classes/pivotlayout.lzx 5: classes/photo.lzx 6: classes/photocollection.lzx 7: classes/clipboard.lzx 8: classes/favorites.lzx 9: classes/search.lzx 10: classes/photocollection.lzx 11: classes/draggedphotos.lzx 12: classes/dataman.lzx 13: classes/spinner.lzx 14: views/mybutton.lzx 15: classes/../views/mybutton.lzx 16: classes/linkbutton.lzx 17: resources.lzx 18: views/tools.lzx 19: views/error.lzx And the same for the calendar demo, which used some LPS components: ringo ~/src/git/kamijs/lzxdoctool/lzxdoc.js -a calendar.lzx List of LZX files for this app: 1: calendar.lzx 2: resources.lzx 3: cal-button.lzx 4: lz/scrollbar.lzx skipping LPS component lz/scrollbar.lzx 5: gridsliderlayout.lzx 6: basepanel.lzx 7: cal-data.lzx 8: event.lzx 9: day.lzx 10: basepanel.lzx 11: base/basetabslider.lzx skipping LPS component base/basetabslider.lzx 12: textbox.lzx 13: infopanel.lzx 14: simpletimelayout.lzx 15: dayname.lzx 16: selected-daylook.lzx 17: eventselector.lzx 18: loading.lzx If anyone is interested in working on the XSLT transformation with me, that would be cool. If not, I'll probably need 1-2 weeks to finish the tool. On Tue, Jan 11, 2011 at 12:02 PM, Raju Bitter < [email protected]> wrote: > I'm moving this over to the dev mailing lists, since I have a bunch of > questions to the dev team: > > 1) The general need for a doctool > It seems that there is no documentation generation tool available for LZX > code as part of the OpenLaszlo platform. I know Webtop has some very basic > documentation, which seems to be generated out of the LZX code. How does > that work, and will that be part of the OpenLaszlo platform? If not, do you > consider a platform with a custom language (LZX) complete - even if you > don't provide up-to-date documentation tools? Do you plan to ship up-to-date > documentation tools at all with a future releases? The Python script which > is available is really simple. It generates simple HTML docs for any LZX > class found in any LZX file in defined folders. And there's no official > support for that tool. > > 2) The OpenLaszlo platform documentation vs. documenting custom LZX code > Based on my research it appears that the documentation found at > http://svn.openlaszlo.org/openlaszlo/trunk/docs/src is currently only used > to document the OpenLaszlo LFC classes and component classes shipped with > the platform. Has that documentation process ever been used to document > custom LZX code, or even one of the demo apps? The stylesheet at > http://svn.openlaszlo.org/openlaszlo/trunk/docs/src/xsl/lzx2js2doc.xsl(transforming > LZX into j2sdoc format) is not fit to work with custom LZX > applications, for some reasons: > a) LZX component dependencies (<include href="lz/window.lzx" /> will > cause the stylesheet to look for an 'lz' folder relative to the LZX file > containing the include). > b) Inclusion of a library path (<include href="someFolder" />) will cause > the stylesheet to load the directory instead of the contained library.lzx > file, causing an exception > c) What if the LZX file contains a class written in JavaScript? It's not > going to be documented. > > The lzx2js2doc.xsl transforms LZX into the jsdoc format ( > http://wiki.openlaszlo.org/JS2Doc_Conversion). Does it make sense to use > js2doc as intermediary format? > > 3) 3rd party solutions > Maybe there's already an existing doctool within the community which could > be published as open source. Are you aware of any solutions? Is anyone from > the community willing to contribute code, or work on an implementation? > There was LazDoc in 2005, but that's totally outdated by now: > http://freshmeat.net/projects/lazdoc/ > > 4) What should be added to the docs? > a) classes, attributes, events, methods > b) class information (inheritance, mixins) > c) stylesheets (internal/external, to give an overview of the styles > defined for the app, and where that specific style information can be found) > d) resources (list of static resources) > > What's missing here? How should runtime-specific switch-blocks be handled, > where you have different implementations of a class depending on the > runtime? > > Then, it would be good to have a doctool supporting different versions of > LZX, since the language evolves so quickly. If you generate the docs, you > should have a version switch '--version 4.9'. Many of the larger projects > are still using older versions of OpenLaszlo. > > On Tue, Jan 11, 2011 at 10:08 AM, Raju Bitter < > [email protected]> wrote: > >> The Python script is just scanning through defined lzdirs, picking up any >> *.lzx file. I'm working on a RingoJS/Rhino based script now, source code >> will be available at https://github.com/kamiJS/lzxdoctool in the next >> days. >> >> >> On Fri, Jan 7, 2011 at 11:48 PM, P T Withington <[email protected]> wrote: >> >>> Pretty sure that you just give it a file and it follows the <include>s in >>> the file. That's how the components get documented. (And why they fail to >>> show up when someone adds a component but does not add it to the relevant >>> library.lzx so that the doc tool will find it.) >>> >>> Not a perfect mechanism by any means... >>> >>> On 2011-01-07, at 17:03, Raju Bitter wrote: >>> >>> > Which mechanism is used to identify all files which make up one >>> application? >>> > Does anyone know how I can point to one LZX file and generate a list of >>> all >>> > other LZX files I'd need to process? >>> > >>> > On Fri, Jan 7, 2011 at 10:39 PM, Raju Bitter < >>> > [email protected]> wrote: >>> > >>> >> Thanks, Tucker. That's what I guessed, that we have to use the XSLT >>> >> transformation. I'm currently looking at this page, let's see how far >>> I get >>> >> with that. >>> >> http://www.openlaszlo.org/lps4.9/docs/developers/doc-toolchain.html >>> >> >>> >> >>> >> On Fri, Jan 7, 2011 at 10:13 PM, P T Withington <[email protected]> >>> wrote: >>> >> >>> >>> Our doc tool maintainer is on sabbatical (:-0). I was able to fix a >>> bug >>> >>> in the tools by reading the doc doc. It's pretty well written. >>> >>> >>> >>> Basically OL use a bunch of XSLT to walk over the LZX and output >>> something >>> >>> that docbook understands and then use docbook to create the final >>> doc. >>> >>> >>> >>> I expect it would be reasonably easy to use the tools on your own >>> LZX. >>> >>> The complicated stuff is the bit that walks over the LFC JS and >>> outputs >>> >>> something that the LZX XSLT can parse... >>> >>> >>> >>> On 2011-01-07, at 16:05, Raju Bitter wrote: >>> >>> >>> >>>> Guess that means: no new tool available. Besides what's built into >>> the >>> >>> LPS >>> >>>> for generating the OL docs. >>> >>>> >>> >>>> On Wed, Jan 5, 2011 at 8:33 PM, Raju Bitter < >>> >>>> [email protected]> wrote: >>> >>>> >>> >>>>> What is the recommended tool for generating LZX documentation? The >>> wiki >>> >>>>> lists the following tools: >>> >>>>> http://wiki.openlaszlo.org/Development_Tools#Documentation_Tools >>> >>>>> >>> >>>>> The page on the LzxdocTool has not been updated since 2007. Does >>> that >>> >>> still >>> >>>>> work with the 4.8 version of OL? >>> >>>>> http://wiki.openlaszlo.org/LzxdocTool >>> >>>>> >>> >>>>> - Raju >>> >>>>> >>> >>> >>> >>> >>> >> >>> >>> >> >
