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

How to automate help file generation

Topics: Developer Forum, Project Management Forum, User Forum
Nov 22, 2010 at 10:09 AM

We've been using the old 1.6 version of Sandcastle for continuous integration because it had a command line mode. That was helpful to specify wildcard options like [-assembly=myasm\*.dll]. Newly added assemblies would automatically get included in the help file without any manual intervention.

Now we have to switch to the latest version for .net 4.0 support, but it doesn't have any command line mode. The project file once created, won't take newly added assemblies automatically.

Any suggestions on how to automate the process?

Nov 22, 2010 at 9:39 PM

If you can, use the Visual Studio solution or project files as the documentation sources.  That way, SHFB will figure out which assemblies, comments files, and references to include in the build automatically.  See the help topic on building projects outside the GUI as it covers the various command line options that you can use to override project properties as well as target override files which can be used to specify a set of project properties in a small, separate project file that will override the main project properties.



Nov 23, 2010 at 2:05 PM

Hi Eric,

Even if we use projects as doc sources, we'll have to add any new project to the SHFBproj manually, via GUI. We want Sandcastle to pick up new assemblies/projects automatically, like the old version used to. Basically, we want to create a single SHFBproj, just once, and run MSBuild on it daily to generate up-to-date help file.

Can you issue a patch or something which will enable adding wildcard entries as the doc sources? For instance, SomeFolder\*.dll, AnotherFolder\*.xml, etc. It would be perfect.


Nov 23, 2010 at 4:53 PM

Actually, it supports that already.  Add the documentation source and then edit the filename in the SourceFile property to replace it with a wildcard.



Nov 24, 2010 at 9:24 AM

Thanks Eric,

Wildcards worked with doc sources. Half the problem solved! But, I couldn't add references as wildcards. Any workaround for that?

Nov 24, 2010 at 6:51 PM

One more thing, Eric. While running BuildAssembler, I got the warning: SharedContentComponent: Missing shared content item. Tag:'include'; Id:'topictitle'.

and then the error: SharedContentComponent: Error replacing item.

I'm using the June 2010 version of sandcastle with the latest styles patch applied. What could be the reason for error?

Nov 27, 2010 at 7:14 PM

I'm not sure of the exact cause.  It could be that something is invalid in the Sandcastle resource files.  Note that the Prototype and Hana presentation styles aren't well supported anymore so be sure you are using the VS2005 presentation style.  If you are doing that already, I'd suggest uninstalling Sandcastle, making sure nothing is left in the C:\Program Files (x86)\Sandcastle folder, reinstalling, and apply the Sandcastle Styles patch again.



Nov 27, 2010 at 7:25 PM

Yes, I was using VS2005 presentation style. I'll try reinstalling then.

What about adding references as wildcard entry? Can it be done?


Nov 27, 2010 at 11:30 PM

Wildcard references can probably be done.  I've had a request for it in the past but haven't looked into it yet.  I will at some point.



Nov 30, 2010 at 8:11 PM

Eric, there's been a problem in generating reflection file. MRefBuilder gives unresolved assembly references error for two assemblies, though they're added as reference in the project and SHFB log shows it had loaded those files as dependencies.

I peeked into the temporary working folder, where an intermediate MRefbuilder.rsp file was generated by SHFB. It lacked /dep: options for those two assemblies among many others.

Why might SHFB be dropping reference entries before passing them over to MRefBuilder tool ? (considering that they're in fact required)

P.S. : GenerateRefInfo.proj file, which I suppose creates MRefbuilder.rsp, has entries for those two assemblies.

Dec 1, 2010 at 8:30 PM

I'd have to see an example project.  Can you e-mail me one that demonstrates the problem?  My e-mail address is in the About box in the GUI and in the footer of the pages in the help file.



Dec 6, 2010 at 10:48 AM

I've mailed you the problematic project and relevant files.

From: karan.bulbule AT gmail DOT com

Subject: issue: Sandcastle Help File Builder [Thread:235557]

Please have a look at it and suggest a solution, as help file generation is an integral part of our daily build process and it's not working since many days.

Dec 7, 2010 at 8:29 PM

I will probably get to it some time this week or this weekend when I have some time to look at it.