Building ASDocs with ANT
In this running series of creating an ANT script to run your Flex based life I feel like we’ve reached some midway point. We have our application being built off of a Flex Library, building the default Adobe html-wrapper along with our own custom wrapper while keeping the non-embedded assets intact.
Now I feel is a good time to start taking care of the more advanced parts of our discussion: documentation, unit tests, and automated testing. Right now, documentation.
As your code base continues to grow the ability for new developers to look over all of your code to understand what is going on is going to shrink exponentially. That is why we include documentation within our code, and we use ASDocs to pull out that documentation and format it into a pretty set of html files.
In this post I’m not going to explain ASDocs as I have explained ASDocs in this post about Actionscript Components and this post about MXML Components.
With all of your components successfully documented it’s time to use the ASDoc tool to actually build html files. This executable runs off of command line and therefore can be run via ANT or Maven also. Since we are discussing ANT I will show you that code.
The idea here is to clean out the old ASDoc folder and rewrite the asdocs. For this we will need two targets and one main target with two dependents.
The Main ASDoc Target
1 2 | <!-- asdoc main --> <target name="asDocs" depends="cleanASDoc,compileASDoc" description="build of asdocs" /> |
The Clean Script
1 2 3 4 5 6 7 8 9 | <!-- Delete the existing output folder and files and then regenerate the output folder --> <target name="cleanASDoc"> <echo>Deleting ASDoc Directory...</echo> <delete dir="${Asdoc.dir}" failOnError="false" includeEmptyDirs="true" /> <echo>Deleted ASDoc Directory</echo> <echo>Creating ASDoc Directory...</echo> <mkdir dir="${Asdoc.dir}" /> <echo>Created ASDoc Directory</echo> </target> |
The ASDoc Executable Script
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | <!-- Run the ASDoc executable and generate the ASDocs to the new output folder --> <target name="compileASDoc"> <echo>ASDoc Compiling...</echo> <exec executable="${AsDocs.executable}" failonerror="true"> <arg line="-doc-sources '${AppClasses.dir}'" /> <arg line="-doc-sources '${LibrarySrc.dir}'" /> <arg line="-external-library-path '${LibrarySrc.dir}'" /> <arg line="-external-library-path '${Library.dir}/${LibraryLibs.dir}'" /> <arg line="-main-title '${Main.title}'" /> <arg line="-window-title '${Window.title}'" /> <arg line="-output '${Asdoc.dir}'" /> <arg line="-footer '${Footer.text}'" /> </exec> <echo>ASDoc Compile Complete</echo> </target> |
The executable tag points our exec task to the proper executable file ready for arguments just like running in command line. Within this block you will see a variety of argument lines, we will go through each of those one at a time so they all make sense.
- doc-sources – a path to the source files to document. I’ve included multiple of these to document both the application and the library, you can use one or multiple of these lines.
- external-library-path – a path to additional libraries to include but not document. This is important because without it the build will fail if your code requires additional swcs to run. I’ve included multiple of these to document both the application and the library, you can use one or multiple of these lines.
- main-title – the main title at the top of all ASDoc pages.
- window-title – prefix title of the window
- output – output directory
- footer – footer of each ASDoc page
To properly make this build I’ve added a few properties to my build.properties file. The additions are below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | ##################################################################### # # ASDoc Properties # ##################################################################### #asdoc output Asdoc.dir=asdoc #the location of asdocs on your computer AsDocs.executable=${FLEX_HOME}/bin/asdoc.exe #Asdoc Footer Text Footer.text=Some legal jargon #window title Window.title=Window Title #main title Main.title=Main Title #the location of your application classes on your computer AppClasses.dir=${basedir}/src |
Our Current Project
Use view source to see our entire project along with build scripts and build properties.
[...] This post was mentioned on Twitter by Joseph Burchett and HowDo.us, CT. CT said: Flex News: Building ASDocs with ANT: In this running series of creating an ANT script to run your Flex based life … http://bit.ly/c6B6aY [...]
[...] you have any troubles understanding this post, make sure to revisit some of the older in this series as I assume you already have your build file and properties file set [...]
[...] will work right into your continuous integration script. Now you can make a release quality build, document it, and run both unit tests and automated tests against your application. Final Touches One final [...]
[...] page. Related Posts: Intellisense – Making your components work with the Flash Builder IDE Building ASDocs with ANT August 10th, 2010 in Best Practices, Flash Builder 4, General | tags: asdoc, component [...]