{"id":645,"date":"2009-01-11T12:46:51","date_gmt":"2009-01-11T11:46:51","guid":{"rendered":"http:\/\/www.navision-blog.de\/2009\/01\/11\/how-i-do-continuous-integration-part-iv-adding-a-documentation\/"},"modified":"2009-01-13T09:00:48","modified_gmt":"2009-01-13T08:00:48","slug":"how-i-do-continuous-integration-part-iv-adding-a-documentation","status":"publish","type":"post","link":"http:\/\/www.navision-blog.de\/blog\/2009\/01\/11\/how-i-do-continuous-integration-part-iv-adding-a-documentation\/","title":{"rendered":"How I do Continuous Integration with my C# \/ F# projects &#8211; part IV: Adding a documentation"},"content":{"rendered":"<p>In the last 3 posts I show how to set up a Continuous Integration environment for F# or C# projects with Subversion (<a href=\"http:\/\/www.navision-blog.de\/2009\/01\/08\/how-i-do-continuous-integration-part-i-setting-up-source-control\/\">part I<\/a>), TeamCity (<a href=\"http:\/\/www.navision-blog.de\/2009\/01\/08\/how-i-do-continuous-integration-part-ii-continuous-integration-server\/\">part II<\/a>) and NUnit (<a href=\"http:\/\/www.navision-blog.de\/2009\/01\/08\/how-i-do-continuous-integration-part-3-running-automated-unittests\/\">part III<\/a>).<\/p>\n<p>This time I want to show how we can set up an automated documentation build.<\/p>\n<h5>Installing and using GhostDoc<\/h5>\n<blockquote><p>\u201cGhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments for C#. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters.\u201d<\/p>\n<p align=\"right\">[<a href=\"http:\/\/www.roland-weigelt.de\/ghostdoc\/\">product website<\/a>]<\/p>\n<\/blockquote>\n<p>GhostDoc is one of my favorite Visual Studio plugins. It allows me to generate comments for nearly all my C# functions. Of course these generated comments aren\u2019t sufficient in every case \u2013 but they are a very good start.<\/p>\n<p><em>Unfortunately GhostDoc doesn\u2019t work for F# \ud83d\ude41 \u2013 the actual version works for C# and the support for VB.Net is called &#8220;experimental&#8221;.<\/em><\/p>\n<p>Download and install <a title=\"http:\/\/www.roland-weigelt.de\/ghostdoc\/\" href=\"http:\/\/www.roland-weigelt.de\/ghostdoc\/\">http:\/\/www.roland-weigelt.de\/ghostdoc\/<\/a>.<\/p>\n<p>Now you should be able to generate XML-based comments directly in your C# code:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Using GhostDoc\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image.png\" alt=\"Using GhostDoc\" width=\"500\" height=\"165\" \/><\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Generated XML-comment\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_3.png\" alt=\"Generated XML-comment\" width=\"500\" height=\"194\" \/><\/p>\n<p>The next step is to activate the xml-documentation in your Visual Studio build settings:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"image\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_4.png\" alt=\"image\" width=\"500\" height=\"206\" \/><\/p>\n<p>Commiting these changes and adjusting the build artifacts will produce the input for the documentation build:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Adjust the build artifacts\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_5.png\" alt=\"Adjust the build artifacts\" width=\"500\" height=\"297\" \/><\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Build artifacts\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_6.png\" alt=\"Build artifacts\" width=\"500\" height=\"171\" \/><\/p>\n<h5>Using Sandcastle to generate a documentation<\/h5>\n<blockquote><p>\u201cSandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:<\/p>\n<ul>\n<li>Works with or without authored comments<\/li>\n<li>Supports Generics and .NET Framework 2.0<\/li>\n<li>Sandcastle has 2 main components (MrefBuilder and Build Assembler)<\/li>\n<li>MrefBuilder generates reflection xml file for Build Assembler<\/li>\n<li>Build Assembler includes syntax generation, transformation..etc<\/li>\n<li><strong>Sandcastle is used internally to build .Net Framework documentation<\/strong>\u201d<\/li>\n<\/ul>\n<p align=\"right\">[<a href=\"http:\/\/www.microsoft.com\/downloads\/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&amp;displaylang=en\">Microsoft.com<\/a>]<\/p>\n<\/blockquote>\n<p>Download and install \u201cSandcastle &#8211; Documentation Compiler for Managed Class Libraries\u201d from <a href=\"http:\/\/www.microsoft.com\/downloads\/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&amp;displaylang=en\">Mircosoft\u2019s downloadpage<\/a> or <a title=\"http:\/\/www.codeplex.com\/Sandcastle\" href=\"http:\/\/www.codeplex.com\/Sandcastle\">http:\/\/www.codeplex.com\/Sandcastle<\/a>.<\/p>\n<p>For .chm generation you also have to install the &#8220;<a href=\"http:\/\/msdn.microsoft.com\/library\/default.asp?url=\/library\/en-us\/htmlhelp\/html\/hwMicrosoftHTMLHelpDownloads.asp\">HTML Help Workshop<\/a>&#8220;. If you want fancy HTMLHelp 2.x style (like MSDN has) you need \u201cInnovasys HelpStudio Lite\u201d which is part of the <a href=\"http:\/\/www.microsoft.com\/downloads\/details.aspx?familyid=59EC6EC3-4273-48A3-BA25-DC925A45584D&amp;displaylang=en\">Visual Studio 2008 SDK<\/a>.<\/p>\n<blockquote><p>\u201cHelpStudio Lite is offered with the Visual Studio SDK as an installed component that integrates with Visual Studio. HelpStudio Lite provides a set of authoring tools you use to author and build Help content, create and manage Help projects, and compile Help files that can be integrated with the Visual Studio Help collection.\u201d<\/p>\n<p align=\"right\">[<a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/bb165613(VS.80).aspx\">MSDN<\/a>]<\/p>\n<\/blockquote>\n<p>Last but not least I recommend to install the <a href=\"http:\/\/www.codeplex.com\/SHFB\">Sandcastle Help File Builder (SHFB)<\/a> \u2013 this tool gives you a GUI and helps to automate the Sandcastle process.<\/p>\n<blockquote><p>\u201cSandcastle, created by Microsoft, is a tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comments files. The current version is the May 2008 release. It is command line based and has no GUI front-end, project management features, or an automated build process like those that you can find in NDoc. The <strong>Sandcastle Help File Builder<\/strong> was created to fill in the gaps, provide the missing NDoc-like features that are used most often, and provide graphical and command line based tools to build a help file in an automated fashion.\u201d<\/p>\n<p align=\"right\">[<a href=\"http:\/\/www.codeplex.com\/SHFB\">product homepage<\/a>]<\/p>\n<\/blockquote>\n<p>After the installation process start SHFB to generate a documentation project:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Sandcastle Help File Builder\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_7.png\" alt=\"Sandcastle Help File Builder\" width=\"500\" height=\"374\" \/><\/p>\n<p>Add the TestCITestLib.dll to your project and add nunit.framework.dll as a dependency. Now try to compile your help project \u2013 if everything is fine the output should look something like this:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Generated Help\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_8.png\" alt=\"Generated Help\" width=\"500\" height=\"193\" \/><\/p>\n<h5>Setting up the documentation build<\/h5>\n<p>One of the main principles of Continuous Integration is \u201c<a href=\"http:\/\/martinfowler.com\/articles\/continuousIntegration.html#KeepTheBuildFast\">Keep the Build Fast<\/a>\u201d \u2013 so I am working with staged builds here. The documentation build should only be started if the first build was successful and all UnitTests are positive. <em>For most projects it is enough to generate the documentation daily or even weekly.<\/em><\/p>\n<p>First of all we have to create a simple MSBuild file which executes the SHFB project:<\/p>\n<pre class=\"code\"><span style=\"color: blue;\">&lt;<\/span><span style=\"color: #a31515;\">Project <\/span><span style=\"color: red;\">ToolsVersion<\/span><span style=\"color: blue;\">=<\/span>\"<span style=\"color: blue;\">3.5<\/span>\" <span style=\"color: red;\">xmlns<\/span><span style=\"color: blue;\">=<\/span>\"<span style=\"color: blue;\"><a href=\"http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003\">http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003<\/a><\/span><a href=\"http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003\">\"<span style=\"color: blue;\">&gt;\r\n<\/span><\/a>  &lt;!-- <span style=\"color: green;\">3rd Party Program Settings <\/span><span style=\"color: blue;\">--&gt;\r\n  &lt;<\/span><span style=\"color: #a31515;\">PropertyGroup<\/span><span style=\"color: blue;\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515;\">SandCastleHFBPath<\/span><span style=\"color: blue;\">&gt;<\/span>c:\\Program Files (x86)\\EWSoftware\\Sandcastle Help File Builder\\<span style=\"color: blue;\">&lt;\/<\/span><span style=\"color: #a31515;\">SandCastleHFBPath<\/span><span style=\"color: blue;\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515;\">SandCastleHFBCmd<\/span><span style=\"color: blue;\">&gt;<\/span>$(SandCastleHFBPath)SandcastleBuilderConsole.exe<span style=\"color: blue;\">&lt;\/<\/span><span style=\"color: #a31515;\">SandCastleHFBCmd<\/span><span style=\"color: blue;\">&gt;\r\n    &lt;<\/span><span style=\"color: #a31515;\">SandCastleHFBProject<\/span><span style=\"color: blue;\">&gt;<\/span>HelpProject.shfb<span style=\"color: blue;\">&lt;\/<\/span><span style=\"color: #a31515;\">SandCastleHFBProject<\/span><span style=\"color: blue;\">&gt;\r\n  &lt;\/<\/span><span style=\"color: #a31515;\">PropertyGroup<\/span><span style=\"color: blue;\">&gt;\r\n\r\n  &lt;<\/span><span style=\"color: #a31515;\">Target <\/span><span style=\"color: red;\">Name<\/span><span style=\"color: blue;\">=<\/span>\"<span style=\"color: blue;\">BuildDocumentation<\/span>\"<span style=\"color: blue;\">&gt;\r\n    &lt;!-- <\/span><span style=\"color: green;\">Build source code docs <\/span><span style=\"color: blue;\">--&gt;\r\n    &lt;<\/span><span style=\"color: #a31515;\">Exec <\/span><span style=\"color: red;\">Command<\/span><span style=\"color: blue;\">=<\/span>\"<span style=\"color: blue;\">%22$(SandCastleHFBCmd)%22 %22$(SandCastleHFBProject)%22<\/span>\" <span style=\"color: blue;\">\/&gt;\r\n  &lt;\/<\/span><span style=\"color: #a31515;\">Target<\/span><span style=\"color: blue;\">&gt;\r\n&lt;\/<\/span><span style=\"color: #a31515;\">Project<\/span><span style=\"color: blue;\">&gt;<\/span><\/pre>\n<p>Add this build file and the SHFB project to your Visual Studio solution folder and commit these changes.<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Put the build settings into the solution folder\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_9.png\" alt=\"Put the build settings into the solution folder\" width=\"240\" height=\"328\" \/><\/p>\n<p>Now we can create a new TeamCity build configuration:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Create a new build configuration\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_10.png\" alt=\"Create a new build configuration\" width=\"500\" height=\"425\" \/><\/p>\n<p>Take the same Version Control Settings like in the first build but use MSBuild as the build runner:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Take the MSBuild runner\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_11.png\" alt=\"Take the MSBuild runner\" width=\"500\" height=\"392\" \/><\/p>\n<p>We want the documentation to be generated after a successful main build so we add a \u201cdependency build trigger\u201d:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"image\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_12.png\" alt=\"image\" width=\"500\" height=\"217\" \/><\/p>\n<p>Now we need the artifacts from the main build as the input for our documentation build:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"Set up artifacts dependencies\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_13.png\" alt=\"Set up artifacts dependencies\" width=\"500\" height=\"326\" \/><\/p>\n<p>Be sure you copy the artifacts to the right directory as given in your .shfb-project. Now run the DocumentationBuild \u2013 if everything is fine the DocumentationBuild should give you the Documentation.chm as a new artifact:<\/p>\n<p><img loading=\"lazy\" class=\"bordered\" style=\"display: inline\" title=\"image\" src=\"http:\/\/www.navision-blog.de\/images\/HowIdoContinuousIntegrationwithmyCFproje_CE61\/image_14.png\" alt=\"image\" width=\"500\" height=\"110\" \/><\/p>\n","protected":false},"excerpt":{"rendered":"<p>In the last 3 posts I show how to set up a Continuous Integration environment for F# or C# projects with Subversion (part I), TeamCity (part II) and NUnit (part III). This time I want to show how we can set up an automated documentation build. Installing and using GhostDoc \u201cGhostDoc is a free add-in [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[12,23,448,29,3],"tags":[492,664,504,498,505,506,508,190,499,174,507],"_links":{"self":[{"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/posts\/645"}],"collection":[{"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/comments?post=645"}],"version-history":[{"count":3,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/posts\/645\/revisions"}],"predecessor-version":[{"id":658,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/posts\/645\/revisions\/658"}],"wp:attachment":[{"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/media?parent=645"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/categories?post=645"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.navision-blog.de\/blog\/wp-json\/wp\/v2\/tags?post=645"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}