This project has moved and is read-only. For the latest updates, please go here.

Passing dynamic references to Sandcastle Help File Builder

Topics: User Forum
Jun 10, 2014 at 12:41 PM
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">
    project="${SourceURL}\Documentation\API Documentation\APIs.sln"
    <property name="OutputPath" value="${OutputPath}Documentation" />
    <property name="ReferencePath" value="${OutputPath}wwwroot\\bin\\" />
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?

Note: I've also asked this on stackoverflow
Jun 10, 2014 at 4:05 PM
ReferencePath is for reference assemblies only, those referenced by the documented assemblies, not the documented assemblies themselves. I'm not familiar with NAnt so unfortunately, I can't provide any help as to why it isn't working. You might try defining OutDir and pointing it to the location of the assemblies. That's what MSBuild uses but that assumes you are using a project as a documentation source in the SHFB project.

Jun 10, 2014 at 4:47 PM
Hi Eric,

Thanks for the reply - I am using a full SHFB project/documentation source - it's fine when built inside visual studio etc.

The OutDir property appears as though it will fix it - it's now complaining about it not find the dll inside the folder I've pointed it to, and it isn't there by design, so I need to tweak the build process itself now...

Thanks again!

Jun 11, 2014 at 9:43 AM
Just to confirm that using OutDir fixed that problem - though there seems to be a wierd issue (documented here also) that it needs to end in a double slash, else msbuild attempts to concatenate it to the project folder...

I'm now having a different issue that the chm won't open - it's reporting:
Cannot open the file:
Other chms open fine, as does this one when built on my local machine using the visual studio integration. Could our build server be missing part of the compilation toolset?
Jun 11, 2014 at 9:59 AM
Bit more info - the file that won't open that's been built from the build server is 1,403KB - whilst the one built locally that does open is only 917KB.
Jun 11, 2014 at 12:01 PM
Bit more googling turned up another thread on here - changing the topic naming method to hashed members has worked for me
Jun 11, 2014 at 4:15 PM
Edited Jun 11, 2014 at 4:16 PM
Failure to open a help 1 file sometimes means all the required bits aren't there for the help 1 compiler or the viewer. Reinstalling the HTML Help Workshop on the affected PCs usually fixes such issues. I'm not sure why changing the naming method would have any effect unless you were using the "member name" method and the filenames (including the path) got too long which is a possibility if it was built in a different folder.

Jun 11, 2014 at 4:28 PM
It was using the GUID option originally. The Working folder is created in a path that is already 50 characters long - I wonder if the hash method is marginally shorter than the GUID option and is therefore sneaking under the limit. I've not inspected the contents of the working folder - I assume there could be some fairly length sub folders/files in there while it's doing it's job?

Is there a way to set the location of the Working folder to be a different location to the final output? I'm now worried that this issue may reoccur if we have a slightly longer namespace involved or something later on down the line. If I can set the working folder elsewhere, that would be a simple solution (and be a good test to see if changing it back to GUID fixes the issue)
Jun 11, 2014 at 6:34 PM
The Working Folder property in the Paths category will let you specify where the working folder is placed. By default, it's .\Working under the Output Path folder which, unless changed, defaults to a .\Help folder under the project folder. So [Project Path]\Help\Working\ is the default unless changed.