Tomorrow I’m handing in my final project for my CS studies. This project is built in C#, and I was looking for a way to automatically create documentation that will aid browsing and understanding the main classes and their functions.
A friend had told me about Sandcastle and I looked it up. Sandcastle is a project by Microsoft, that is intended to create MSDN-style documentation from .NET assemblies…
I had managed to achieve my goal quite easily using Sandcastle, and I thought about sharing my experience to serve other people as a guide. This is just a quick write-up of what I did – I did not read Sandcastle’s documentation and I believe that I don’t know how to operate it to its full potential.
- The first step is to download and install Sandcastle.
- Next, if you haven’t done it already, you have to tell Visual Studio to build XML documentation files. This parses all your comments ( in the C# format ///<summary> etc…) and creates an XML file that we will feed into Sandcastle. To enable XML documentation, you have to go to Proect->(Project Name) Properties… and tick the relevant checkbox in the Build menu:
- We will now launch the Sandcastle GUI application, located in C:\Program Files\Sandcastle\Examples\generic ( replace C:\Program Files with wherever you had installed Sandcastle).
- Add your assemblies (exe/dll) and XML comments file to the relevant list boxes and choose the desired output format. Enter you project name under “Name”.
- Hit “Build”. The build process can take a while, and it may seem like the program is frozen, but it’s not.
- Your documentation files should now be ready in C:\Program Files\Sandcastle\Examples\Your Project Name
- If you chose CHM as an output format, you will now have to compile the CHM file. To do this you need to download and install Microsoft HTML Help Workshop
- After installing HTML Help Workshop, you will have to run hhc.exe (from the directory where you installed it). hhc takes an hhp (HTML Help Project) file as an argument. Sandcastle has created this hhp file for you, and it should be in your Sandcastle project directory. Just run “hhc yourproject.hhp” and this will produce a CHM file in the project’s directory.
That’s it. You should now have your compiled CHM help file with nice MSDN-style documentation.
As I mentioned earlier, I don’t really know Sandcastle and will be happy to get some tips in the comments section if you have any.