blogs.conchango.com

I found more things to do with sandcastle after part 1 and part 2. Here's a trick that made the sandcastle build simpler. The basic problem is that sandcastle must run after all the binaries are built by projects in a solution (so that it can read those binaries), but before the WiX installer is built (so that the sandcastle output can be packaged by WiX).

WiX V3 can be a project in the solution, but Sandcastle is unfortunately not. Life would be easier if it was, and I hope that some day it will be, but for now we must make do. And we can make do with a dummy project. The procedure is as follows:

Create an empty project called "MyProject.Documentation" in your solution. In the project dependencies, make sure that it depends on all the projects that build binaries that will be documented, and that the Wix installer depends on it. So now it's in the right place in the build order, between the binaries and the WiX

Now fire up your text editor and edit the MyProject.Documentation.csproj file. It's an MSBuild script, which means that previous tricks can be applied, i.e. create or replace the build target with the following line:

  <Target Name="Build" DependsOnTargets="BuildSandcastleDocs">

  </Target>

So now the build step has been rejigged to skip compilation of the (non-existent) source files of this project, and instead build the sandcastle. The BuildSandcastleDocs is similar to in the last few posts, but not identical:

Above that the following definitions:

  <PropertyGroup>

      <SHFBConsolePath>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</SHFBConsolePath>

  </PropertyGroup>

  <ItemGroup>

     <SandcastleProjects Include="$(MSBuildProjectDirectory)\*.shfb" />

  <SandSources Include="

$(MSBuildProjectDirectory)\..\MyProject.UI\Bin\$(Configuration)\*.exe;

$(MSBuildProjectDirectory)\..\ MyProject.UI\Bin\$(Configuration)\*.dll; $(MSBuildProjectDirectory)\..\ MyProject.UI \Bin\$(Configuration)\*.xml" 

      />

  </ItemGroup>

  <Target Name="BuildSandcastleDocs">

      <!-- Build source code docs -->

      <Message Text="Copying @(SandSources) to $(OutDir)" />

      <Copy SourceFiles="@(SandSources)" DestinationFolder="$(OutDir)" />

      <Message Text="Building projects for sandcastle:@(SandcastleProjects)" />

      <!-- Update the output path -->

      <Message Text="Replacing OutDir with $(OutDir)" />

      <Attrib Files="@(SandcastleProjects)" ReadOnly="false"/>

      <FileUpdate Files="@(SandcastleProjects)" Regex="\$\(OutDir\)" ReplacementText="$(OutDir)" />

      <Exec Command="&quot;$(SHFBConsolePath)&quot; &quot;@(SandcastleProjects)&quot; -outputpath=&quot;$(OutDir).&quot;" />

  </Target>

The main change from last time is SandSources, a group of files of type *.exe, *.dll and *.xml which are copied to the Sandcastle project's output dir.  This is done to make it work on a dev machine as well as on a build server. On the build server, all projects share the same $(OutDir), but on a dev  machine all projects use different ones.

On a local machine it copies binary files from the last project's output dir to the Sandcastle project's output dir.  On a build server this doesn't need to be done. However this step does nothing on the build server, since no output files are located in those folders. So the build works both ways now.

Actually we have two versions of the solution – one with the Sandcastle and wix projects for CI use; and a faster one without for constant desktop use.