External Dependencies

Topics: General Questions
Dec 20, 2007 at 3:49 PM
If I add a number of assemblies to the DocProject properties can I copy these from one DocProject project to another?

I ask 'cos I'm going to be creating a number of documentation projects that all need to access the same set of files and wanted to just add them the once.

Dec 21, 2007 at 12:51 AM
Hi Stuart,

All references (project and external) are stored in the project file itself. Project references are written to <ProjectReference> elements and external sources are listed in the <UserProperties ExternalSources="..." /> attribute. Add some references to a DocProject or DocSite and then search the project file for these settings. All DocProject-compatible project templates support this data.

You may be interested in the following work item for a feature that would allow you to reference a folder as an external source (i.e., everything within the folder is a source) instead of having to reference individual files:

Allow Folders as Sources

- Dave
Dec 21, 2007 at 7:22 AM

thanks for that.

I have arelated question, if that's OK.

As I suggested in my initial post, I have a number of projects that use 3rd party components. I have the components properly registered as references in my DocProject project, but when I compile the help the links to those components are 'dead', that is they aren't clickable links.

I can get around this my adding the assemblies (and their .XML files) as external dependencies but this results in much bigger file and a much longer compile time.

As I have access to the .HxS files for each of these components, I wondered if there were some magic spell I could use to link in to them rather than having to, effectively, regenerate the help files for each of these components in the help for each of my projects.

I should prolly point out that the help (mine, that is) will only be installed on machines that also have the 3rd party components (and thus, their help files) installed.

Dec 21, 2007 at 10:47 AM
Edited Dec 21, 2007 at 10:49 AM
EDIT: Originally I had said to open the Help 1.x build component stack, when in fact it should be the 2.x stack since that's used to build .HxS output.

Hi Stuart,

I haven't tried this myself but others seem to have had success linking to third-party .HxS files from within Sandcastle's output. There's some information in this thread:

Sandcastle: Links Between Project Outputs (HxS)

To have Sandcastle generate links you need to have reflection information for the target assemblies. The DocProject Properties window allows you to configure the build component stacks for your project, which contain a build component that resolves external references. If you expand the Help 2.x build component stack property, for example, you'll see the component named, Reference Link Types. Expand this component and you'll see its built-in support for two types of links: .NET Framework, which resolves links using the MSDN web service by default, and Project, which resolves local links between HTML files generated by Sandcastle for your project. Select the link types and look at the descriptions. Notice that each one references one or more reflection XML files (hard-coded or using a wild card pattern). Click the ellipses (...) button on the component itself (not the individual link type properties) and the configuration file will open in the Visual Studio XML editor. The component's first line will be selected if you're configuring the project from within VS; otherwise, just look for the component named, ResolveReferenceLinksComponent2. You need to add additional <targets> here that point to the third-party .HxS files' reflection data in order for links to work. Although you probably don't have reflection data for them, so you'll have to generate it yourself. You can generate reflection data using Sandcastle's MRefBuilder.exe program on the command-line (check the example batch script for usage info). You'll need the managed assemblies, of course.

DocProject configures Sandcastle to look for XML documentation in the project's buildhelp\assembler\Comments folder. You can either use your project's Build Process Component to copy the third-party documentation to this folder (if you need help just ask) or you can add a new path to the same configuration file that you just had opened. Find the component after <!--Copy in comments--> and simply add a new <data> element that points to a path in the project; e.g, <data files="..\..\Help\ThirdPartyDocs\*.xml" />

Note that I'm planning on creating editors for the built-in components so that they all work similarly to Reference Link Types, and I'm also going to add an editor for that component so that you can manage targets without having to open the configuration file. I don't think this feature will make the next release, but I do plan on adding it soon.

- Dave