Ages ago, NDoc- a jDoc clone- was the best free .NET documentation-generating application in town. For various reasons, that project shut down, and Microsoft released it's internal documenting system, Sandcastle, to the public. However Sandcastle by itself is non-trivial to understand and implement. It's designed to gen up the entire MSDN documentation site, so it can be overwhelming for creating docs for your small line-of-business app.
Enter Sandcastle Help File Builder. This gem brings back the simplicity and open source spirit of NDoc, and adds some functionality from Sandcastle to provide a great documenting solution for small or large projects. I'd checked it out in earlier versions, but it's come a long way. It even has a console app, which can easily be integrated into your continuous integration process. In addition, you can add documents other than the typical xml-doc and build a true compiled help that a developer may actually use.
Here's how we set ours up:
- A solution has a _FileReferences project for file-based dll references and other non-compiled code. (Build is false for all Build configurations). This project contains:
- a Help folder that contains .htm files and the compiled .chm file
- a .shfbproj file that manages the documentation project.
- In the .shfbproj:
- A site map has been added to build the table of contents. It has nodes pointing to each .htm file.
- The solutions' projects have been added as Documentation Sources.
- An automated process downloads the solution from source control, checks out the .shfbproj and .chm, runs the console app to generate a new .chm, and checks everything back in.
This way, the documentation is constantly updated and available in source control alongside the project!
|Share this post :|
We use this at work to build the docs for online and offline for our framework. Good stuff!
Post a Comment