Suggest using ItemGroup instead of PropertyGroup in SHFBPROJ DocumentationSources definition

Topics: Developer Forum
Jul 30, 2009 at 3:54 PM
Edited Jul 30, 2009 at 3:57 PM

I am currently transitioning our builds from ant and nant to team build.  In the case of the ant and nant builds the build product generally ends up in the release (or debug) subfolder.  The Sandcastle projects are hardwired to find the component product and their xml files in relation to the component's project.

Team Build, on the other hand, places all build product (.exe, .dll, .xml) in a binaries\release folder.  The shfbproj file that I used for the ant or nant builds doesn't work.  I've used msbuild properties and manually edited the shfbproj to make the path locations a bit more flexible but don't have a good generic solution.

It occurs to me that some of this might be solved by defining an ItemGroup for DocumentationSources rather than using a property with subelements.  

Here is a clip to use as a base example:

<PropertyGroup>
...
   <DocumentationSources>
       <DocumentationSource sourceFile="$(pathtocomponent1product)\Component1.dll" xlmns=""/>
       <DocumentationSource sourceFile="$(pathtocomponent1product)\Component1.xml" xlmns=""/>
       <DocumentationSource sourceFile="$(pathtocomponent2product)\Component2.xml" xlmns=""/>
       <DocumentationSource sourceFile="$(pathtocomponent2product)\Component2.dll" xlmns=""/>
  </DocumentationSources>
...
</PropertyGroup>

In this case the msbuild invocation will have to define the properties "pathtocomponent1product" and "pathtocomponent2product".

The alternative I might suggest is to define an ItemGroup, <DocumentationSources> that provides the paths.  The help file builder GUI could generate the following SHFBProj content that achieves the same purpose as the PropertyGroup, something like this:

<ItemDefinitionGroup>
   <DocumentationSources>
      <xlmns></xlmns>
</ItemDefinitionGroup>

<ItemGroup>
   <DocumentationSources Include="Path\To\Component\Product1\Component1.dll"/>
   <DocumentationSources Include="Path\To\Component\Product1\Component1.xml"/>
   <DocumentationSources Include="Path\To\Component\Product2\Component2.dll"/>
   <DocumentationSources Include="Path\To\Component\Product2\Component2.xml"/>
</ItemGroup>

 The advantage is that then I only need to define a property for a single common path and use relative paths.

I would change (manually) the values above to.
<ItemGroup>
   <DocumentationSources Include="$(CommonPath)\**\Component1.dll"/>
   <DocumentationSources Include="$(CommonPath)\**\Component1.xml"/>
   <DocumentationSources Include="$(CommonPath)\**\Component2.dll"/>
   <DocumentationSources Include="$(CommonPath)\**\Component2.xml"/>
</ItemGroup>

Then I could pass the property CommonPath and all components would be found.

Obviously, the msbuild target that processes this would have to be modified.  The fact that it changes the format of the shfbproj is likely reason to avoid making changes but the affected targets could be designed to accomodate legacy implementation (PropertyGroup defined DocumentationSources).

This may be of benefit only to me but it seems like it would allow a more general treatment of locating source files.

Dick

Coordinator
Jul 30, 2009 at 6:18 PM

I don't use Team Build so all I have to go in is the information others have supplied in the Team Build help topic (http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/ec822059-b179-4add-984d-485580050ffb.htm).  You might review that to see if there's information that will help.  As I understand it, Team Build defines the OutDir variable to indicate where all of the project output is located.  Another thing you should consider is using the Visual Studio solution or project files as the documentation sources.  By doing that, SHFB will automatically locate the assemblies and comments files as well as all referenced assemblies.  SHFB takes the OutDir variable into account when parsing the projects so it should find the proper items when using Team Build.

Eric