Monday, December 6, 2010

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




No comments: