 |
ASP Kitchen |
|
ASP Kitchen |
An ASP Documentation Tool™This article describes the ASP Documentation Tool™, a utility I wrote to automate the documentation of web applications developed using ASP 2.0 or 3.0 and the VBScript and JScript scripting languages. When developing applications using Java and Perl, I've always been impressed with the JavaDoc and PerlDoc documentation utilities these languages support. When producing work for a client, these utilities take a lot of the hard work out of the mundane (but critically important) work involved with documenting the project. Unfortunately there is no such standard documentation utility for ASP, and having not found a suitable commercial offering, I decided to write my own documentation utility for ASP. Since I often work on projects inherited from other developers, such a utility would be able to give a useful overview of the project without having to manually look through the ASP code. The utility would also (hopefully!) create much of the low level documentation required when handing over work to clients, saving valuable development time.
FeaturesThe ASP Documentation Tool™ scans all the files of a web project, and outputs a report based on what it finds within the files. The report contains a list of the following:
The report is produced in standard HTML [view sample], with an option to export the report in Microsoft's HTML Help [view sample] and plain text format [view sample]. The HTML output can be viewed in any web browser on any operating system. By contrast, the HTML Help format is restricted to machines running Microsoft Windows. HTML Help does, however, have some useful advantages over the standard HTML output:
System RequirementsThe ASP Documentation Tool™ is written in Perl 5, but has been compiled into a Windows executable file that can be used on any machine without requiring Perl. If you want the ASP Documentation Tool™ to create a report in HTML Help format then you will need to download and install the HTML Help Workshop. This is a free download from Microsoft.com. It is strongly recommended that you install the HTML Help Workshop to the default location, which is C:\Program Files\HTML Help Workshop. If the HTML Help Workshop is installed elsewhere then the ASP Documentation Tool™ will need to be modified to change the value of the variable called "HTMLHelpProg". Configuring and Running the ASP Documentation Tool™The ASP Documentation Tool™ is installed using a standard Windows installation routine. There is a graphical user interface - The ASP Documentation Tool™ Configurator - for configuring documentation jobs. The ASP Documentation Tool™ executable file must be supplied with several command line options which control the behaviour of the script and the appearance of the output report. There are just two mandatory command line options, which are used to specify the input folder (i.e. the folder containing the ASP files that are to be documented) and the output folder (i.e. where the report should be placed).
So the following command when typed in the folder in which the ASPDocumentationTool.exe resides would document the web project in C:\inetpub\wwwroot\mywebsite and output the report in the folder D:\reports\mywebsite: ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite" Note that the script will overwrite a previous report in that folder. The following command line options are optional:
As an example, the ASP Documentation Tool™ could be called from the command line using: ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite" --cs=1 --v=0 --hh=1 --project="SampleWeb" Don't forget that it is possible to run the ASP Documentation Tool™ on Windows machines from .bat scripts, which can of course be scheduled using the AT command or the Windows Task Scheduler. The ASP Documentation Tool™ reports are created in standard HTML, which can be subsequently edited using any HTML editor. The HTML Help format output may also be edited by using Microsoft's HTML Help Workshop - the HTML Help Workshop project file is created in the output folder along with the rest of the report, and it has a .hhp file extension.
The ASP Documentation Tool™ creates a log file in plain text format [view sample]. Obtaining the ASP Documentation Tool™See downloads section below The evaluation version is fully functional, but has a few limitations, including:
The full version of the ASP Documentation Tool™ is available for online purchase from RegSoft from just $49.99. Purchasing the ASP Documentation Tool™ allows you to download the current version, and all subsequent versions released up to six months from the date of purchase. Comments/Suggestions?I've released the ASP Documentation Tool™ in the hope that other users may find it useful! If you would like new features added, then don't hesitate to contact me - most user requests are incorporated into future releases! Downloads
Further readingUseful Development Tools
Author detailsBrett Burridge has worked as a web developer since 1997 and has developed web applications for a range of corporations, start up busiensses and educational establishments. Brett is presently employed as an Internet developer and technical writer through his own company, Winnersh Triangle Web Solutions Limited. The company produces a number of innovative products, including a range of software documentation tools, which include the ASP Documentation Tool™, the .NET Documentation Tool for VB.NET and C#, and the SQL Server Documentation Tool. Other products include The Website Utility, which functions as a website error checker, search engine optimizer and ASP/ASP.NET search engine builder application. As well as the ASPAlliance, Brett has written articles for Ariadne.ac.uk, ASPToday, the software documentation portal www.softwaredocumentation.info, and has contributed recipes to the ASP.NET Developer's Cookbook. links Outside web development, Brett is interested in travelling (here are my travel logs from New York, Hong Kong and Tokyo), digital photography (here's my photo gallery), tropical fishkeeping and collecting contemporary works of art by artists such as Doug Hyde. Contact Brett by emailing
Article history"An ASP Documentation Tool™" published on ASPAlliance.com on 02 June 2002, last revised 11 September 2006. ASP Kitchen: Classic ASP Articles: An ASP Documentation Tool™ |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| © page content copyright Brett Burridge 1998 - 2008. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
