I have been working with Steve Bohlen of late in evaluating a couple of API documentation engines that are being considered for inclusion with NHibernate's API.
One issue that was bothering me was how to best deal with detecting assembly changes in a Project. As many of you know NHibernate has a rather extensive API that undergoes many regular changes and additions. DocProject is one tool that is being evaluated to perform the documentation requirements. During the initial project setup a wizard prompt requests you to select your assembly targets for inclusion. These assemblies then appear as reference dependency inside of your DocProject project. So the question that was bothering me was what happens if you create new assemblies? Having to manually added these new assemblies to DocProject would become a nuisance as it would be easy to forget to do this step.
Stephen suggested the following which worked quite nice!
Step 1
Remove the reference assemblies from DocProject
After removing the dependencies, you need to specify an external location where they can be located by DocProject. Below this is done within the DocProject Properties window supply we supply the External sources location for the source of the assemblies and the XML documentation files.
Step 2
Create a post build event that copies the Assemblies to the projects output directory which in this case we have created a folder output target called Help. This folder content is also automatically cleaned and scrubbed by the projects build script during the compile task. We added the following macro command in the Project Properties | Build Events section defining a post-build event.
Checking the noted changes caused a fail to the build. We need to automate the creation of the Help folder.
Hence I added a make directory task to my compile target in the project's build script.
Now any assemblies newly added within my projects namespace will be automatically detected for documentation. The post-build task can be tweaked to limit the project assemblies you would like to document.
