As some of you already know I created some Ant scripts for compiler and manifest generation in Flex Builder. Well I’ve just updated them to include easy inclusion of remote service configuration files. I’ve also extended them so that they now include ASDoc generation tasks.
Now as most Mac Flex Builder users will already know ASDoc will not run from the default path due to the fact that the path name has white spaces in it. There are an awful lot of solutions and hacks out there to get this to operate correctly, but I couldn’t be bothered with half of them, as I suspect a lot of other developers. So I decided to sweat a little blood and write my own :p (and fix the Adobe one in the process). In some parts they are an amalgam of those ideas and pointers that others have applied to getting this resolved. I personally approached it from a slightly different perspective and the scripts here are what I came up with.
So for those into Shell scripting and Ant I have a brief run through of my “solution” below. For those who just want to get going you can download the scripts here.
OK for those still reading here is an outline of what I did. So from a Shell scripting perspective here’s a breakdown:
Firstly I had to deal with the spaces issue in the path names. So I decided the easiest way would be to dynamically create a symlink to the target project for the duration of the process – that way I negate immediately the issue of spaces in the project path.Also by creating it in the users Documents directory I don’t have to worry about permissions or making the user add in passwords.
Next I had to deal with the issues in the ASDoc shell script that Adobe supplied. To be honest the solution is pretty simple. Just put double quotes around the Flex Builder SDK location, in there script they refer to it as the PATH variable $FLEX_HOME (In my script it is called $asdocPath). This also then allows you to use paths with spaces also. So that fixes the pesky Mac issue of the Flex Builder path having spaces in it.
However I thought it would be a big ask to get someone to download my scripts then go hunting around in their directories to change a path in a file they probably didn’t even know, or care, existed. So instead I just took the same java command and included it in my script (fixed of course). I also added in the ability to define an output directory (relative to the project root), a templates directory. Plus window, page and footer variables so you can do a simple bit of customization (if people want more let me know and I’ll add more in). Obviously if you want to make CSS or graphical changes then I suggest you use Dreamweaver or Photoshop as I am not going to make some uber 1337 Ant script that dynamically creates graphics :p
Finally I added in a bit of logic to make sure that the directories are created and deleted (when doing a fresh export) and that if certain values are omitted there is a default to stop the script going too screwy and messing anything up.
On the Ant side it was more a matter of passing the values to the script in a format it liked. In the original version I had the documents directory creation and deletion as a separate localized Ant task. But as the documentation directory can have a default (handled by the script not Ant), and that it seemed a bit overkill for what you got I decided to roll the task into the main documentation process and moved it to the shell script.
The scripts themselves are pretty heavily commented so if you want to have a read through then feel free to. If you have any suggestions or requests just ping me an email via the address in the shell scripts.