Setting up automated builds with sandcastle

Sandcastle Documentation Builder

Found a quicker work around for automated builds with docs.

MSBuild  has some additional functionality (Provided Sandcastle and Sandcastle Help File Builder must be installed first) that makes the documentation process pretty damn easy.

1.Build projects with xml documentation enabled.

2.Sandcastle and Sandcastle Help File Builder must be installed

3.Sandcastle Style May Patch must be applied to sandcastle

4. NET 4.0 must be added to “C:\Program Files(x86)\Sandcastle\ProductionTools \MrefBuilder.exe.config” in sand castle

Ex:

“*< supportedRuntime version="v4.0.30128"/> <!-- 4.0 RC installed by VS2010 RC -->”

5. Create a new project in “SandCastle Help File Builder“and add the projects

6. add all the projects that you want to document.

7.Save and close

8.Depending on how you want the documentation you can create individual shfbproj for individual chm files for each project or you could just have one set of documentation for the entire project

(I’m assuming you just want one in this example)

Place something like the following in your post build event in the last project you are building in your solution.

   1:  

   2: //path of framework

   3: C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe 

   4:  

   5:  

   6: /p:CleanIntermediates=True 

   7:  

   8: //Debug or Release

   9: /p:Configuration=Debug 

  10:  

  11: //Platform AnyCPU, x86, x64

  12: /p:Platform= AnyCPU

  13:  

  14: //Path of the sandcastle help builder project

  15: C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shfbproj

 

You may get a notification from visual studio stating something along the lines of “Visual Studio is awaiting a response” just be patience depending on the size of your project it could take a while….

 

(I have about 9 namespaces and a couple thousand methods it picked up and took about 5-6 minutes to compile.)

   1:  

   2: On Completion it should read something like this

   3:  

   4: Build started 6/17/2010 1:46:52 

   5: PM.

   6: Project

   7: "C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shbproj" 

   8:  

   9: on node 1 (default targets).

  10: SHFB : warning BHT0001: 

  11:  

  12:  Unable to get executing 

  13: project:

  14:  Unable to obtain internal 

  15: reference. The specified project will be 

  16:  

  17:  loaded but command line 

  18: propertyoverrides will be ignored.

  19:  

  20: [C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shfbproj] 

  21:  

  22:  Building 

  23: C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.hfbproj 

  24:  

  25:  Initializing 

  26:  

  27:  ClearWorkFolder 

  28:  

  29:  FindingTools 

  30:  

  31:  ValidatingDocumentationSources 

  32:  

  33:  GenerateSharedContent 

  34:  

  35:  GenerateApiFilter 

  36:  

  37:  GenerateReflectionInfo 

  38:  

  39:  GenerateNamespaceSummaries 

  40:  

  41:  ApplyVisibilityProperties 

  42:  

  43:  TransformReflectionInfo 

  44:  

  45:  ModifyHelpTopicFilenames 

  46:  

  47:  CopyStandardContent 

  48:  

  49:  CopyAdditionalContent 

  50:  

  51:  MergeTablesOfContents 

  52:  

  53:  CreateBuildAssemblerConfigs 

  54:  

  55:  MergeCustomConfigs 

  56:  

  57:  BuildReferenceTopics 

  58:  

  59:  

  60: GenerateIntermediateTableOfContents 

  61:  

  62:  ExtractingHtmlInfo 

  63:  

  64:  GenerateHelpFormatTableOfContents 

  65:  

  66:  UpdateTableOfContents 

  67:  

  68:  GenerateHelpFileIndex 

  69:  

  70:  GenerateHelpProject 

  71:  

  72:  CompilingHelpFile 

  73:  

  74:  CleanIntermediates 

  75:  

  76:  Completed 

  77:  

  78:  

  79:  

  80:  The help file is located at: 

  81:  

  82:  

  83: C:\LearningProject\Branches\Trunk\Doc\Help\Documentation.chm 

  84:  

  85:  Build details can be found 

  86: in 

  87:  

  88: C:\LearningProject\Branches\Trunk\Doc\Help\LastBuild.log 

  89:  

  90:  Done 

  91:  

  92:  Building Project 

  93:  

  94:  

  95: "C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shfbproj"

  96:  

  97: (default targets).

  98:  Build 

  99: succeeded.

 100:  

 101: "C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shfbproj"

 102:  

 103: default target) (1) ->;(CoreBuildHelp target) -> 

 104:  

 105:  SHFB : warning BHT0001: 

 106:  

 107:  Unable to get executingproject: 

 108:  

 109:  Unable to obtain internal 

 110: reference. 

 111:  The specified project 

 112: will be loaded but command 

 113:  line 

 114: property overrides will be ignored.

 115:  

 116: [C:\LearningProject\Branches\Trunk\Doc\LearningProjectDocumentation.shfbproj] 

 117:  

 118:  1 Warning(s) 

 119:  

 120:  0 Error(s)Time Elapsed 

 121: 00:05:18.13