02 May 2014

C# Code Comments: Create Documentation on Build

You can easily create C# documentation from code comments using Sandcastle.

  1. After installing Sandcastle and it's pre-requisits, create a new Sandcastle configuration and save it in the root of the solution e.g. [Solution Name].shfbproj
  2. Add the Solution file to Documentation Sources on the right hand pain.
  3. Select what formats you wish to create e.g. old style Help file (chm) or Website.
  4. In "Paths" change the Help content output path to your directory of choice. The default is "Help".
  5. Run the build to check it works and check the output.
Add it to the Project Build
Once it's working you can add it to the project build:

Edit the 'start up' project file (usually the website/MVC project) to include an on build event to fire off the documentation build. I only do mine on Release as it's a lengthy process:
</Project>
[rest of project file here...]
<!--Build Docs on release only-->
<Target Name="AfterBuild" Condition="'$(Configuration)'=='Release'">
<Exec Command="C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe /p:Configuration=Release &quot;$(SolutionDir)$(SolutionName).shfbproj&quot;" />
</Target>
<!--/Build Docs on release only-->
</Project>

Notes


  • You may have errors thrown up e.g. if your code comment syntax is invalid (it must be valid XML). I found the log file by default is not detailed enough to show you exactly where the error lies so you will need to change the level of detail: Build; BuildAssembler Verbosity to "All Messages". Once the error is fixed you'll probably want to change this back to Only Warnings and Errors as it slows down the process.
  • I also use GhostDoc to provide a comment framework but note these comments need to be edited and augmented.

No comments:

Post a Comment