Search code examples
sandcastlexml-comments

MS Sandcastle - Is there any quick way to "preview" what the output will be without recompiling the entire help?

Well, the title asks it all.

I have the Sandcastle Help File Builder GUI. I can generate help files, but I was wondering if there was a faster way of seeing the results aside from recompiling the entire help file.

I asked about Sandcastle because other tools I've tried that offer a preview feature don't compile help files to the exact specification as does Sandcastle. Most of them require fully qualified references, which is a pain in the butt.

Solution

  • No, there is no preview capability but there are some SHFB settings that allow you to dramatically reduce build time. In my case, my 16 to 18 minute build was reduced to 3 minutes.

    What you want to adjust are the Cached Build Components. And fear not, adjusting these 3 components requires no arcane manipulations or complex gyrations.

    1. Simply go to the Build section in the SHFB GUI, and find the line near the top labeled ComponentConfigurations.
    2. Click on the value field to reveal a hidden ellipsis (...) button.
    3. Click that button to open the Select and Configure Build Components dialog.
    4. Select in turn each of the three entries beginning Cached... and select the Add action.
    5. These require no configuration so close out the dialog and if successful the main SHFB window should now indicate 3 custom build component(s).

    Be sure to review the documentation at the above link for more details.

    Just for completeness, two other items of interest:

    Take a look at this forum post (Sandcastle build is taking hours to complete) that discusses how your hardware can have a tremendous impact on Sandcastle build time as well.

    Take a look at my article Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code on Simple-Talk.com that discusses quite a lot of tips and pitfalls of Sandcastle and SHFB--ironically I uncovered my tip here about cached build components after that article went to press so you will not find it in there!