Creating HTML documentation in C# using Visual Studio and Sandcastle

I had a coworker ask me today about creating documentation in C#/.NET ala javadoc by rendering embedded developer remarks into HTML.  It’s actually pretty simple to do because most developers use the built-in XML documentation features of Visual Studio when they are authoring their code.  Anyways, the short version is that the following steps will allow you to generate documentation for your code using existing tools:

Authoring XML comments and documentation

To author XML comments and documentation, the minimum you should do is type /// before your methods and Visual Studio will create templates of XML content that you can then “fill in the blanks” on. The following code shows an example of some XML documentation:

        /// <summary>                                                            
        /// Processes the request based on the path.                             
        /// </summary>                                                           
        /// <param name="context">Contains the request and response.</param>     
        public void ProcessRequest(HttpContext context)                          
        {
            // Code, code, code, code...  
        }

Compiling the documentation into an XML file

To enable compilation of the documentation into XML, you need to enable and configure the output from your build to include documentation. Open the Project -> Properties menu and then enable the XML documentation option.  If the option is grayed out, you might need to press SHIFT+F5 to break from a currently running program. The following screen shot shows XML documentation as enabled in a project that I had laying around.

Now, when I perform builds, the bin folder will have an Output.XML file within it that I can then use for generating documentation. If I were a real programmer I would then use an XSLT to translate this XML into an HTML document.  However, I am not going to do this, because I’m lazy. Instead, let’s use a freely available tool, sandcastle.

Use sandcastle to build documentation

Now that you have an XML file with your documentation in it, it’s a good time to convert the documentation into a reference.  There are various shipping vehicles for documentation in Windows, from which compiled help documentation (.chm files, pronounced like “chum”), is the most backwards compatible and which I prefer, and HTML 2.0 documentation files (.HxS aka “the documentation with no way to view it”) which is what is used for the current offline experience for MSDN documentation.

All that aside, you probably are eager to pump out some sweet, sweet, documentation.  The Microsoft authored version of Sandcastle has long been abandoned so make sure you get the community sourced version of Sandcastle before continuing.

After you download Sandbox, extract it and run the installer.  I’ll warn you that the going through installer is not the greatest experience.  Just keep clicking the install boxes on the right half of the dialog at each step to get all of the dependencies. Once the installer has successfully completed, you are ready to build some docs!

Open the Sandcastle Help File builder GUI which is installed to “C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder” by default.  When you open the builder, it looks like this:

Select File->New Project and you will get the project build dialog for an empty project.  The build will by default not have any files added.  Right click documentation sources as seen in the following screenshot and add the XML file generated in the previous step.

Now you have configured your project to build the documentation and all you have left to do is build it!  Press the build button, which has the two down arrows, and your documentation will be built.

Conclusions

Building documentation from C# sources is trivial once you have the tools setup.  When you author C# code, make sure to include the appropriate XML markup in your code!