How to Customize the ASDocs Main Page

Recently I was lucky enough to be able to go back through and revise all the documentation I did for a set some of my favorite science center kiosks. I have a hunch that the code for the kiosks will be open-sourced; so I will make sure to post links when they become available. The documentation was intended to be targeted at Actionscript and Flash developers, so I figured ASDocs would be the perfect candidate. There were a few frustrating hurdles at first; but ASDocs is a pretty straightforward tool once you get it working.

After generating ASDocs output I was thinking: well, "how can I add to this documentation more pages containing downloads, descriptions, or customized HTML within the CSS that ASDocs uses?" I originally went down the road of appendices; but the most popular resources provide broken template replacements; so that didn't work for me. So I got to looking at the ASDoc output and templates and figured out how to show my own index instead of the default listing of packages when the ASDocs documentation initially loads. So how did I customize that first page? I generally took an approach outside the ASDoc xslt paradigm, so here it is.

1. I first copied the default ASDoc templates to a local path, then explicitly pointed to them in my Apache Ant ASDoc script I put together using the -templates-path parameter. By default the asdocs templates are usually in your base Flex directory, then at asdoc/templates. I copied the whole folder into another location.

2. The second thing I did was I modified the index.html page inside my copied ASDocs templates folder to point to a custom external manualDocs folder and getting-started html page.

3. The getting started html page was a copied instance of the default output "package-summary.html" page that I modified to include all the documentation. (I renamed it to getting-started.html and made all the CSS and javascript references point up a directory).

4. After that I just went nuts in the getting-started.html page and manualDocs folder for files, images, and references pointing back into the ASDocs output. Because ASDocs is all framed, it looks like my index page belongs right in the action.

The caveat here is that there isn't a good way back to the main getting-started.html page unless you get into more depth with modifying the rest of the templates.

Trouble With the Flash IDE

These kiosks were developed in the Flash CS4 IDE due to their massive amount of static visual components to help speed up layout of clips.

The Flash IDE and ASDocs don't work very well together because ASDocs uses the Flex compiler so it has no clue about Flash Professional library items. It also has no clue about exported classes in the IDE. So the first task of using ASDocs with a Flash Professional project is to export a SWC of the project that contains all the items exported in the library. The next annoying task is to rename all on-stage/in movieclip/in sprite UI items using dynamic means. So lets say inside my clip:

mcCoolClip I had a property: mcCoolClipOnStageChild

I'd normally be able to reference it when compiling from the IDE with just: mcCoolClipOnStageChild.whatever

Not so with ASDocs as it has no clue about IDE created references. So you have to re-name any uses of clip-contained properties/classes with their dynamic syntax:

this["mcCoolClipOnStageChild"].whatever

great; well that took 40 hours when I had two projects with 50 classes or more.

My advice with ASDocs as a beginner would be to go through the pain of figuring out how to use it at the beginning of a project instead of the end; so you don't have to go back and modify a whole bunch of classes. The FlashDevelop IDE still provides superior auto-completion for comments and everything else over Flashbuilder 4.5 (in Windows), so I'd recommend that.