msbuildnantsandcastleshfb

Passing dynamic references to Sandcastle Help File Builder

I've been using Sandcastle Help File Builder for a while to generate documentation - I'm now trying to get it to be part of our build process. Our build is controlled using NAnt, and each time it's built the output gets sent to a different location (based on changeset numbers, so we can have concurrent builds without clashes) - ie the dlls are not in a fixed path relative to the source code.

I've added a target into the NAnt script to call SHFB, which invokes the msbuild task, pointing at the solution that contains the SHFB project:

<target name="GenerateDocumentation">
  <msbuild
    project="${SourceURL}\Documentation\API Documentation\APIs.sln"
    verbosity="Detailed">
    <property name="OutputPath" value="${OutputPath}Documentation" />
    <property name="ReferencePath" value="${OutputPath}wwwroot\\bin\\" />
  </msbuild>
</target>

I've specified the ReferencePath property, as on this page, it seems to indicate that this would allow SHFB to find the assemblies and use them, rather than relying on the information in the original project file:

If the ReferencePath property is defined, it will be passed to and used by GenerateRefInfo.proj when generating reflection information. This allows you to specify an alternate path in which to find reference assemblies that will override hint paths in the project file.

However when the build reaches this point, it fails with the following error:

SHFB: Error BE0040: Project assembly does not exist: D:\Build\Debug\wwwroot\bin\MyAssembly.dll

Which is the default output path specified in the original project.

What is the correct mechanism for passing the location of the assemblies into SHFB?

Solution

  • Turns out that using OutDir instead of ReferencePath is the way to go:

    <target name="GenerateDocumentation">
  <msbuild
    project="${SourceURL}\Documentation\API Documentation\APIs.sln"
    verbosity="Detailed">
    <property name="OutputPath" value="${OutputPath}Documentation" />
    <property name="OutDir" value="${OutputPath}wwwroot\bin\\" />
  </msbuild>
</target>

    Also note that the path specified in OutDir must end in a double slash, otherwise MSBuild attempts to concatenate it with the project path