Sandcastle + OpenTK.xml is very slow

Topics: User Forum
Oct 6, 2014 at 12:55 PM
Edited Oct 6, 2014 at 1:39 PM

I use OpenTK in my project. When I add OpenTK.xml to my documentation sources and click on build, it need very much time.

You can reproduce it by using the Nuget package of OpenTK:
  1. Create a project
  2. Add Documentation project (Sandcastle Help File Builder project)
  3. Nuget: "install-package OpenTK"
  4. Build project
  5. Add OpenTK.xml from build output to "Documentation Sources"
  6. Build Documentation (Beware! Needs much time!)
A build took 22 Minutes on a i7-4770 (3,4 GHz) building a CHM and 1:01:59h on my laptop building a HTML site. That is not acceptable in Visual Studio (effectively I cannot work for this time). In the GUI it may works in the background but in case you want to change a typo and check the site, you need to wait an hour...

Is there a faster way? I think I only need to compile OpenTK.xml once every OpenTK-Version. After that I only need to link the new stuff to existing sites.
Oct 6, 2014 at 4:22 PM
Unless you really want OpenTK documented in your help file, add it as a reference assembly not a documentation source. Better yet, use your Visual Studio solution or project file as the documentation source and SHFB will figure out what it needs to use for documentation and reference assemblies. If you're just trying to get the inherited comments and suppress the invalid link warnings, use the Additional Reference Links plug-in.

Oct 7, 2014 at 12:53 PM
It's mostly to supress warnings. I had my solution in documentation sources and there are some warnings about "can't find Matrix2" or similar. To get this away, I added OpenTK to documentation sources.

I created a new project with OpenTK as documentation source and build it. In the first documentation I added the plug-in with the new project as reference.

I build it: 24 minutes. better than 1 hour but still very slow.
Oct 7, 2014 at 3:02 PM
You don't need to build the other project used in the plug-in. If in Visual Studio and you've added the reference project to the solution, just use the Configuration Manger to indicate that it shouldn't be built. The plug-in will run a partial build to get the reference information which is all that's needed.

Oct 8, 2014 at 3:43 PM
FYI, here are the timings from our most recent ten-hour website build on SHFB The resulting html folder contains 1,403,539,782 bytes in 117,284 files.

<buildStep step="Initializing">
<buildStep step="ClearWorkFolder">
<buildStep step="ValidatingDocumentationSources">
<buildStep step="GenerateSharedContent"> Last step completed in 00:00:00.5330
<buildStep step="GenerateApiFilter"> Last step completed in 00:00:02.0260
<buildStep step="GenerateReflectionInfo"> Last step completed in 00:01:52.1440
<buildStep step="GenerateNamespaceSummaries"> Last step completed in 00:00:05.6230
<buildStep step="ApplyVisibilityProperties"> Last step completed in 00:00:08.5800
<buildStep step="GenerateInheritedDocumentation"> Last step completed in 00:00:43.5610
<buildStep step="TransformReflectionInfo"> Last step completed in 00:11:12.5620
<buildStep step="CopyAdditionalContent"> Last step completed in 00:00:00.7410
<buildStep step="MergeTablesOfContents"> Last step completed in 00:00:00.0080
<buildStep step="GenerateIntermediateTableOfContents"> Last step completed in 00:00:59.0480
<buildStep step="CreateBuildAssemblerConfigs"> Last step completed in 00:01:08.0860
<buildStep step="MergeCustomConfigs"> Last step completed in 00:00:03.9540
<buildStep step="BuildReferenceTopics"> Last step completed in 01:50:00.6094
<buildStep step="CombiningIntermediateTocFiles"> Last step completed in 00:00:06.2713
<buildStep step="ExtractingHtmlInfo"> Last step completed in 02:42:11.9003
<buildStep step="CopyStandardHelpContent"> Last step completed in 00:00:11.2981
<buildStep step="GenerateHelpFormatTableOfContents"> Last step completed in 00:00:00.0350
<buildStep step="GenerateFullTextIndex"> Last step completed in 02:14:17.4297
<buildStep step="CopyingWebsiteFiles"> Last step completed in 03:12:39.4679
<buildStep step="CleanIntermediates"> Last step completed in 00:11:20.8741
<buildStep step="Completed">
Build completed successfully at 09.12.2014 10:11 . Total time: 10:27:11,2058

I wonder how Microsoft builds MSDN Library nowadays.
Oct 8, 2014 at 5:20 PM
Oh... that is... lot of time. I am really happy that mine needs only 1 Minute now. And no more warnings. Thank you :)

I wonder how much time you sat on writing the comments and all the things... I guess (assuming 70% of the html is documentary text) ~1 GiB of text is not written in a week or two.
Oct 9, 2014 at 6:26 AM
The documentation was generated from XML comment files that total 35,622,986 bytes, so the percentage is closer to 2.5% than 70%. And the input files have a lot of XML overhead for <member> elements and indentation. Of course, the output also includes the summaries of inherited members from Microsoft.