LazDoc
From OpenLaszlo
A GPL C# application to generate a doc System for laszlo IN laszlo
Apr 12, 2006 @ Washington Publishing Company:
"In working with Laszlo, we found the need to generate documentation from our code. Doing some looking around the Laszlo Site, there are a lot of tools, but we did not see anything to help us generate documents.
This led us down the path of building a Laszlo Document Builder. Why LazDoc? WPC's Laszlo Documentation Tool
Sure, we could have built .CHM files or an HTML help system, but that would not have taken advantage of Laszlo itself. The basis for this project really came from two places. The first is from Javadoc and NDOC, documentation generation tools that our development staff uses, and the other came from the Laszlo Reference Manual , the manual uses a Laszlo Application as a Help System referencing HTML pages for content. "
Wayback Machine link to dead lzdoc site
As the real site is down,wayback can be really sluggish & has no pics, I post the ingredients here:
Contents |
LazDoc Introduction
Figure 1. Laszlo Reference Screenshot
Having a Flash Application that contains Help references to documentation of our own Laszlo Files gave us a great way to present the documentation. After some careful examination of how Laszlo was building their help files, we decided to tackle this project. There are two major components to pulling this off. The first is determining the way we to extract documentation from Laszlo Files, and the second is how we built a new Laszlo Project and related HTML files.
Extracting information from Laszlo is similiar to how Javadoc or NDOC works, and building the Laszlo file that links to the generated help screens is accomplished by building upon the design used in the Laszlo Reference documentation. The inspiration for this was a file called nav.lzx under the LPS Server\docs\reference section of the Laszlo Server. The nav.lzx would be the base for our menu and navigation, and the code extraction would be the base for building the Help Navigation piece. We wrote a seperate, more technical article, on how to go about actually generating Laszlo documentation: it can be found with the downloads. Our source code reader has a Laszlo Template built for the files being scanned.
Of course everything in this project is released under the GNU. Building and Displaying LazDoc Files
The main application for generating documentation from LZX files is called LazDoc and has a home page on WPCLabs
Building upon the way the Laszlo Documentation is built, our approach uses a Web Page with two frames. A Navigation frame that contains our Laszlo Application, and a results frame that contains the HTML output from the documentation we generate. The basic layout is shown below:
Figure 2. LazDoc Output Structure
Building LazDoc Files
The first application is a C# (Visual Studio .NET) solution allowing you to scan 1 or more Laszlo files and extract documentation from them. This application performs all of the core steps in evaluating Laszlo source files, extracting documentation, and building the output files. Main functions of the application include the ability to build and view your Laszlo documentation.
- Selecting Laszlo Files to Generate Documentation
- Building LazDoc Files
- Run Laszlo/Tomcat
- Open LazDoc Files
For the builds, it is assumed that a local copy of the Laszlo Presentation Server is running. The LazDoc application saves files in a location under the server, this can be set in the application configuration of course.
A screenshot of the LazDoc application, in the Version 0.2 state, is shown below.
Figure 3. LazDoc Application
Displaying LazDoc Files
Once your LazDoc files are generated, the next step is to view them from your Laszlo Presentation Server. The LazDoc application builds a LZX file as well as HTML files for the source Laszlo file. All of these are published to the Laszlo Server. Launching them from the Step 4 button on the LasDoc generator application lets you see the results of your work. Below is a simple example output screen of the output generated from LazDoc.
Figure 4. LazDoc Help File
Summmary and Future Efforts
This is our first release of LazDoc and we have learned a ton about both Laszlo and the effort in building documentation from Laszlo source files. Having good documentation from our Laszlo files is an important step for us in having well supported and documented applications. Building the documentation with Flash Output gives us another option from a .CHM file for help.
The richness of Laszlo applications gives us a great platform, and as it matures, the tools to support development in Laszlo will also mature. We are excited about the chance to contribute to Laszlo development.
Our roadmap for LazDoc is still coming together, but we have a list compiled of items that we are working to add in the near future. Below is a list of items we have on the plate for future releases.
- Stand Alone Help Files (.SWF files that can be distributed - this can be done via Eclipse currently, but it is not easy to automate)
- Better Search Functionality (this version is very basic)
- Full Flash Help - Hopefully we can get a rich text edit box in Laszlo and skip the HTML all together
- General Cleanup and improvements in the application
If you would like to participate on this project, please let us know on either our Source Forge project, or on WPCLABS. Reference
LazDoc Links
- Washington Publishing Company: Website
- wayback machine link to old site
- Download @ freshmeat
- Download @ sourgeforge
Authors and Contributors to LazDoc
Andrew Plata - works for WPC and has become the local Laszlo Expert. Andrew built the guts of LazDoc. Steve Bass (CEO of WPC) was nice enough to jump in and help get style sheets built. John Wall generated the initial specification as well as building the template Laszlo files for this project. Of course Tim Dutcher, Sean Ottey, John Loeser, and Chris Miller all helped in getting this project up, running and initially tested.
