How does MS build docs for .NET Framework?

Jul 2, 2008 at 9:56 PM
I'm using Sandcastle to build help for a large project (over 300 DLL's).

I have put together an MSBuild project file to do the job. When I run this from command prompt everything is fine.

We use CruiseControl.NET to do our builds. Main MSBuild project on the build machine runs my Sandcastle MSBuild project to build the documentation after every build.
In this setup I always get OutOfMemoryException from BuildAssembler.exe.

So, I was thinking that I would not run MRefBuilder.exe on *.dll, but rather one by one all the way to HTML. But when building TOC reflection.xml is used, which is created in the process before and would only contain data from the last dll.

Can someone shed some light on what is the best practice to build docs for large projects like .NET Framework?


Here is my MSBuild project (or part of it):

  <Target Name="ReflectionData"
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\MRefBuilder.exe" "*.dll" /out:"reflection_base.xml" "/dep:$(NETSourceDir)\bin\*.dll"' />
    <Exec WorkingDirectory="$(WorkingDir)"
          Condition="'$(PresentationStyle)' == 'vs2005'"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\ApplyVSDocModel.xsl" /xsl:"$(ProductionTransforms)\AddFriendlyFilenames.xsl" "reflection_base.xml" /out:"reflection.xml" /arg:IncludeAllMembersTopic=true /arg:IncludeInheritedOverloadTopics=true' />

  <Target Name="Manifest"
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\ReflectionToManifest.xsl" "reflection.xml" /out:"manifest.xml"' />

  <Target Name="Html"
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\BuildAssembler.exe" /config:"$(MSBuildProjectDirectory)\sandcastle.config" "manifest.xml"' />

  <Target Name="Compile"
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\CreateVSToc.xsl" "reflection.xml" /out:"toc.xml"' />


  <Target Name="HxS"
          DependsOnTargets="Clean; Compile"
    <Copy SourceFiles="@(HxsFiles)" DestinationFiles="@(HxsFiles->'$(OutputDir)\%(RecursiveDir)%(FileName)%(Extension)')"/>

    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template.HxF" DestinationFiles="$(OutputDir)\$(HxSFileName).HxF" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_A.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_A.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_B.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_B.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_F.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_F.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_K.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_K.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_N.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_N.Hxk" />
    <Copy SourceFiles="$(DxRoot)\Presentation\shared\HxsTemplate\template_S.HxK" DestinationFiles="$(OutputDir)\$(HxSFileName)_S.Hxk" />

    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\CreateHxc.xsl" "toc.xml" /arg:fileNamePrefix=$(HxSFileName) /out:"$(OutputDir)\$(HxSFileName).HxC"' />
    <Exec WorkingDirectory="$(WorkingDir)"
          Command='"$(ProductionTools)\XslTransform.exe" /xsl:"$(ProductionTransforms)\TocToHxSContents.xsl" "toc.xml" /out:"$(OutputDir)\$(HxSFileName).HxT"' />
    <Exec WorkingDirectory="$(OutputDir)"
          Command='"$(MSBuildProjectDirectory)\Help 2.0 Compiler\hxcomp.exe" -p "$(OutputDir)\$(HxSFileName).hxc"' />

Jul 4, 2008 at 1:55 AM
Edited Jul 4, 2008 at 7:05 AM
Hello Rastio,

>>Rastio: I'm using Sandcastle to build help for a large project (over 300 DLL's).
BTW, .NET performance guide recommends using less dll, but that is not the problem here.

>>Rastio: ...what is the best practice to build docs for large projects like .NET Framework?
Consider building several help topics not just "dll one by one", and if you want you can merge the
results. When carefully done, all the links will be well resolved and there is not need to worry
about large project. The MSDN itself is created from several help files, so you can do the same
instead of trying to build all in a go.
Both the HtmlHelp 1.x and 2.x viewers make it easy to view several files as if merged.

With the Sandcastle Assist project, we are investigating use of database for such things as
the reflection results. It is not ready for use yet, but you might keep an eye on it for later

Best regards,
Jul 7, 2008 at 9:04 PM
Edited Jul 7, 2008 at 9:09 PM
Thanks for your response.

Can you please elaborate on:
>>Consider building several help topics not just "dll one by one", and if you want you can merge the

So I guess, you mean create few HxS files and register all of them and merge them under one namespace?

The equivalent of what I'm trying to do is (hence so many DLL's).

Does this reside in multiple HxS files?

Jul 7, 2008 at 11:26 PM
Hi Rastio,

Maybe this will help: 

Componentization - Building Assembly level HxS using Sandcastle

- Dave
Jul 14, 2008 at 5:29 PM
thanks for your response.

This helped. I have however decided not to build the help on my integration server. The build of just the help takes five and a half hours.

But it helped with the out of memory.