Creating ASDocs with ANT & Flash Builder Part 3. Customizing the Documentation Template.

3. Customizing the HTML template for your Flash Builder Project.

There’s no point doing good work if others don’t know about it or can’t understand what you did. When it comes to developing lengthy applications a well written documentation is a must. A well written documentation which compliments your project’s design shows commitment to the project and a professional feel.

In Part 1 of this tutorial we covered ANT installation. Part 2 explains the best practices for writing comments inside your project’s classes which later are read by ANT and included in the project documentation. Part 3 is the final part of this series. It will help you understand how your documentation is structured, and what can be done to customize the HTML template used by ANT to generate the documentation.
The default documentation template is the same as the one used by Adobe to document the ActionScript 3.0 language. Here is a link which I am sure you have visited before:

Good to know:

What are HTML templates? An HTML template is a ready-made design of the HTML page. The HTML template usually include most of the source files necessary for further customizing the template. It can be edited using WYSIWYG editors such as Frontpage, Dreamweaver etc.

CSS – Cascading Style Sheets is a language used to create stylesheets in which you can describe presentation semantics, its used mainly with HTML and XHTML pages. It can also be used with Adobe Flash Builder and other. It’s a good practice to separate the styling of your project in a CSS file. This way the designer and the developer for example can work together and have a smooth workflow.

Where is the template used by ANT ?

The path to the template should look like this:
/Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/.

Inside the “templates” folder you will find all the components that make the HTML template. You cannot modify the template directly, but you can create a copy and assign it’s path in the ANT build script instead of using the default.

The CSS:

Through this CSS file you can assign styles to all the components that make your documentation pages. You can easily make changes to the documentation pages by modifying the styles.css (path: /Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/style.css).

In order to modify an element’s style you need to begin your declaration with the element’s class name. From then it’s simple. Assign the new properties as shown on the image above.

You can see the class names of the elements you would like to modify by opening the .html files of the template. Here is an example that shows where and how the class is defined for the elements and also how the stylesheet is assigned to the HTML page. If you have found a CSS stylesheet that fits your needs you could even save time and assign it instead of the default one. Then just make sure to change the class names for the elements that require customization. The global settings would stay the same.

Manipulating the HTML itself:

You could manipulate the HTML directly and change the layout of your page as well. I would recommend using Dreamweaver or other free editing software both for the CSS and the HTML. This would help you edit quickly and to see the results immediately as Dreamweaver for example has views that allow you to see the modifications live as you are making them.

Finishing up:

The range of modifications you can make to your template has almost no limits. All you need is a basic understanding of the HTML and CSS language and a good editor software.

Once you are ready to use the template or test it you need to assign it inside your build.xml file. (explained in Part 2) Here’s the example syntax:

<arg line="-templates-path '/Applications/Adobe Flash Builder 4/sdks/4.1.0/asdoc/YourTemplateName'"/>

Above is a snippet of one of CuriousMinds’ project documentation build.xml files.  As you can see there are settings editable directly through the build.xml file like the window-title and other. One of my favorite things to do is to make sure the company branding is displayed as well as the client’s. An ideal place for the Author’s name and the Company branding is the footer (line 66).

This is all there is to customizing you template. If you have any questions post and I will try to be quick to answer.

Happy coding!

About Curious Minds
We are a web development firm in New York and Chicago, providing development resources and consulting for websites and mobile apps since 2004.