Share via

Creating a Chm build using Sandcastle

  • Article

Here are the steps to create a Chm build using Sandcastle. Please see the atatchment for the steps in text format.

Prerequisites:

1. .Net Framework 2.0

2. For Chm generation download HTML Help Workshop - https://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

How do Reference Build From /// Comments using Sandcastle V2.0:

Sandcastle can read authored triple-slash comments embedded in source files.

  1. Sandcastle by default is installed at c:\Program files\Sandcastle. Open a command prompt and type the following:

cd \Program Files\Sandcastle\Examples\Sandcastle

In this directory, you will find only a single C# file called test.cs under Examples\sandcastle directory.

  1. Begin by compiling the C# file and extracting the /// comments.

csc /t:library /doc:comments.xml test.cs

  1. This creates not only test.dll, but also comments.xml file that contains the extracted /// comments
  1. Next, run MRefBuilder:

MRefBuilder test.dll /out:reflection.org

  1. Transform the output

For building using VS2005 transforms please use the following:

XslTransform /xsl:"..\..\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org /xsl:"..\..\ProductionTransforms\AddFriendlyFilenames.xsl" /out:reflection.xml
**
For building using prototype transforms please use the following:

XslTransform /xsl:..\..\ProductionTransforms\ApplyPrototypeDocModel.xsl reflection.org /xsl:..\..\ProductionTransforms\AddGuidFilenames.xsl /out:reflection.xml

  1. Generate a topic manifest

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToManifest.xsl reflection.xml /out:manifest. xml

  1. Create an output directory structure

For building using VS2005 transforms please use the following:

call ..\..\Presentation\vs2005\copyOutput.bat

For building using prototype transforms please use the following:

call ..\..\Presentation\Prototype\copyOutput.bat

  1. Run BuildAssembler using the sandcastle component stack (Note: We are providing VS 2005 transforms under Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder. For building VS2005 format please use sandcastle.config file from C:\Program Files\Sandcastle\Presentation\vs2005\Configuration folder as it uses shared content from C:\Program Files\Sandcastle\Presentation\vs2005\Content and transforms from C:\Program Files\Sandcastle\Presentation\vs2005\Transforms)

BuildAssembler /config:sandcastle.config manifest.xml

to generate topic files in HTM.

  1. Generate HTML help project

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToChmProject.xsl reflection.xml /out:Output\test.hhp

  1. Generate intermediate table of contents

For building using VS2005 transforms please use the following:

XslTransform /xsl:..\..\ProductionTransforms\createvstoc.xsl reflection.xml /out:toc.xml
For building using prototype transforms please use the following:

XslTransform /xsl:..\..\ProductionTransforms\createPrototypetoc.xsl reflection.xml /out:toc.xml

  1. Generate HTML help project information

XslTransform /xsl:..\..\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\test.hhc

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToChmIndex.xsl reflection.xml /out:Output\test.hhk

  1. Run hhc (HTML Help 1.x Compiler) to generate Chm, hhc compiles the Sandcastle target files into a CHM file.

hhc output\test.hhp

Bugs/Feature Requests:

build_Sandcastle.txt

Comments

  • Anonymous
    July 28, 2006
    Where is the link to download it so we can test it?

  • Anonymous
    July 28, 2006
    Is the CTP version released?

  • Anonymous
    July 29, 2006
    Not yet and will come out shortly. I will post a blog as soon as it's out and thanks for your pateince.

    Anand..

  • Anonymous
    July 29, 2006
    Not yet and will come out shortly. I will post a blog as soon as it's out and thanks for your pateince.

    Anand..

  • Anonymous
    July 29, 2006
    Isn´t it going to be a add-in for VS?
    Is it going to have a GUI?

    Thanks,
    Mikael Söderström

  • Anonymous
    July 29, 2006
    The comment has been removed

  • Anonymous
    July 29, 2006
    Okey, great.

    Will there be an SDK so developers can use it in their own applications?

  • Anonymous
    July 29, 2006
    Are you sure that step 4 is correct? I tried it, but nothing happends.

    This is what i tries:
    XslTransform "C:Program FilesSandcastleProductionTransformsAddOverloads.xsl" /out:"D:ProjectsApplicationsTestingSandCastleWindowsApplication1binDebugreflection.org" | XslTransform "C:Program FilesSandcastleProductionTransformsAddGuidFilenames.xsl" /out:"D:ProjectsApplicationsTestingSandCastleWindowsApplication1binDebugreflection.xml"

    I also tried...

    XslTransform "C:Program FilesSandcastleProductionTransformsAddOverloads.xsl" /out:"D:ProjectsApplicationsTestingSandCastleWindowsApplication1binDebugreflection.org"

    ...which prints the whole xml file.

    Is there anything wrong?

  • Anonymous
    July 29, 2006
    Mikael:

    Try taking out the "/out:" before the path to reflection.org.  I'm assuming this file is an input.

  • Anonymous
    July 29, 2006
    Yes and there is no /out in this step. Did you try the test example provided?

  • Anonymous
    July 29, 2006
    The comment has been removed

  • Anonymous
    July 29, 2006
    Thanks, I have successfully created a chm file now.

    But I´ve got some problems with it, I keep getting runtime errors in it all the time. Is this a known problem or have I done something wrong?

    I´m going to post a blog about it and upload all the files soon.

  • Anonymous
    July 30, 2006
    Where am I supposed to implement the comments.xml file?

    I can´t find it in the guide.

  • Anonymous
    July 30, 2006
    If you've always wanted to create MSDN-like documentation for your managed class libraries, you'll want...

  • Anonymous
    July 30, 2006
    Thanks for the instructions. After figuring out the paths issue in the config file I managed to come up with a batch file to perform all these steps. More info here:

    http://ixnay2infinity.blogspot.com/2006/07/batch-file-for-microsoft-sandcastle.html

  • Anonymous
    July 30, 2006
    The comment has been removed

  • Anonymous
    July 30, 2006
    Anand,

    Is it possible to change the XML Comments files path in another way?
    It would be nice to change the path in the bat file instead of the config.

    Thanks,
    Mikael Söderström

  • Anonymous
    July 30, 2006
    mpietsch - You are correct about step 4. Mikael and Ashely have batch file now available and thank you both.

    Sandcastle supports comments in localized version. As I explained above releace comments.xml in sandcastle.config with your comments file or multiple *.xml files.

    Anand..

  • Anonymous
    July 30, 2006
    The comment has been removed

  • Anonymous
    July 30, 2006
    Okey, I get it.

    I will keep experimenting.

    Keep up the good work!

  • Anonymous
    July 30, 2006
    MRefBuilderStatic (v2.0.2397.42473)
    Copyright Microsoft Corp. 2005
    Error: Unresolved assembly reference: Microsoft.Build.Utilities (Microsoft.Build.Utilities, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a) required by xacc

    I have tried adding the dep, no luck... :(

  • Anonymous
    July 30, 2006
    The comment has been removed

  • Anonymous
    July 30, 2006
    Si vous avez toujours voulu créer une documentation comme MSDN pour vos assemblies, vous voudrez sûrement...

  • Anonymous
    July 30, 2006
    It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend....

  • Anonymous
    July 30, 2006
    PingBack from http://born2code.net/?p=41

  • Anonymous
    July 30, 2006
    Aram has a post onhow to build a help file using Sandcastle. The MSBuild extension is not in this CTP

  • Anonymous
    July 30, 2006
    PingBack from http://blog.jkowalski.net/?p=52

  • Anonymous
    July 31, 2006
    The comment has been removed

  • Anonymous
    July 31, 2006
    Please see the Sandcastle CTP announcement here. Additionally, Arnand (Sandcastle team PM) has posted...

  • Anonymous
    August 01, 2006
    Is it posible to exclude classes from the documentation? Eg. by adding an attribute?

    Thank you

  • Anonymous
    August 06, 2006

    This post provides steps to create CHM using Sandcastle. Some of the users have automated these steps....

  • Anonymous
    August 06, 2006
    PingBack from https://blogs.msdn.com:443/sandcastle/archive/2006/08/06/690260.aspx

  • Anonymous
    August 11, 2006
    I've spent some time playing with Microsoft's solution to build documentation based on XML tags in your code. This post gives a brief recap of what I experienced as well as providing links to help you get started.

  • Anonymous
    August 14, 2006
    I've spent some time playing with Microsoft's solution to build documentation based on XML tags in your code. This post gives a brief recap of what I experienced as well as providing links to help you get started.

  • Anonymous
    September 16, 2006
    Update After installing the August CPT of Sandcastle, you'll need to update to the latest version of

  • Anonymous
    September 26, 2006
    The comment has been removed

  • Anonymous
    September 26, 2006
    Step 5 should work. You can email me directly by clicking the Email menu at the top of this page and I will be happy to help.

    Anand..

  • Anonymous
    September 27, 2006
    The sample worked great, the doc generated looks superb. Can't wait to see the finished product!

    Is there a way/script to generate a single chm file from a solution (.sln)

  • Anonymous
    October 20, 2006
    This tools really need the GUI, to complex steps, confusing, and to much error or misunderstanding running the steps.

  • Anonymous
    October 20, 2006
    Ariston, Please visit http://www.sandcastledocs.com or http://codeplex.com/Tagging/TagDetail.aspx?TagName=Sandcastle to download the GUI created by customers. Anand..

  • Anonymous
    November 11, 2006
    Sandcastle generates GUID file names for HTM. With the release of November CTP you can generated friendly

  • Anonymous
    November 17, 2006
    Holy cow, 12 complex steps?!?!  Isn't there a way to make this easier to run?  You should take a look at Javadoc, it makes this type of thing really easy.  Just one command and you get your HTML help.

  • Anonymous
    November 22, 2006
    Check out our help, way cool http://www.entityspaces.net/blog/EntitySpaces152NewSandcastleHelp.aspx We used the Gui builder program, works very well.

  • Anonymous
    February 26, 2007
    I get the following result when i try use XslTransform. Why? what could be wrong? am not a techie person, btw, just trying to find out if a writer can use this one: C:Program FilesSandcastleExamplesSandcastle> ....productionToolsXslTransf orm ....ProductionTransformsAddOverloads.xsl reflection.org XslTransform (v2.2.61208.1447) Copyright c Microsoft 2005-2006 Specify one input XML input file.

  • Anonymous
    March 09, 2007
    Is it possible to produce an HTML web page from these manual steps, rather than (or preferably in addition to) a compiled CHM file? I'm sure there's some obvious flag or setting, but I'm not finding it.

  • Anonymous
    March 14, 2007
    I'm stuck at the second step! After typing typing csc ... at the prompt, I receive a message that csc is not recognized as an internal or external command, operable program or batch file. Suggestions, please?

  • Anonymous
    April 25, 2007
    "Specify one input XML input file" Make sure the XslTRansform commands have the /xsl: argument encloded in "" as in - XslTransform /xsl:"C:Program FilesSandcastleProductionTransformsTocToChmContents.xsl" toc.xml /out:OutputEnergyWorkbench.hhc and not XslTransform /xsl:C:Program FilesSandcastleProductionTransformsTocToChmContents.xsl toc.xml /out:OutputEnergyWorkbench.hhc

  • Anonymous
    June 27, 2007
    In April I blogged about Bertrand Leroy 's, cool document extraction tool (ScriprDoc 1.0) that will generate

  • Anonymous
    September 02, 2007
    I can't get past step 2 either.  I get the message that csc is not recognized as an internal or external command, operable program or batch file. Any ideas?

  • Anonymous
    September 05, 2007
    Anda mungkin sudah membaca tentang SandCastle (gimana ga, tiap buka IDE Visual Studio pasti nongol di

  • Anonymous
    October 02, 2007
    Add the path to csc.exe (most probably C:WINDOWSMicrosoft.NETFrameworkv2.0.50727) to  your environment variables.  Open up System from control panel, choose the advanced tab, click on Environment variables. Select Path from System Variables and choose edit.  Add the path to the end of that list (don't forget to put a semi colon in before to separate it from the existing path).

  • Anonymous
    October 18, 2007
    The comment has been removed

  • Anonymous
    October 18, 2007
    OOPS! I just found the article on generating reflection data. I think this might solve my problem.

  • Anonymous
    October 18, 2007
    I've heard numerous reports about problems with Chm files Vista. Can you tell me if Chm and HTML Help 1.x are supported on Vista and whether Chm is likely to be replaced by "AML-next"?

  • Anonymous
    November 22, 2007
    The comment has been removed

  • Anonymous
    December 11, 2007
    Hi, is it possible to avoid protected members being listed in the result?

  • Anonymous
    August 13, 2008
    I got everything working.  I tried the AddIn, but it doesn't do anything.  Not listing any of my files from the project.  The release seems to be outdated. Is that project still alive?

  • Anonymous
    August 26, 2008
    Ready for some documentation for the ATK controls ? To skip my journey to create this , download the

  • Anonymous
    January 28, 2009
    I always get the same error after running step 2 error cs1024:Preprocessor directive expected. It is in cause of my regions in my code. Is there a possibility to give some argument or something like that to csc.exe that my region will be ignored?

  • Anonymous
    July 11, 2010
    <a href="www.youtube.com/watch title="beach sand castle build">Come learn how to build a drip sand castle at the beach</a>   www.youtube.com/watch

  • Anonymous
    November 25, 2012
    The comment has been removed

  • Anonymous
    February 07, 2013
    Hi, Class's or Method's  /// <summary>  comments were not included in the output .chm file. Thanks, Bhaskar

  • Anonymous
    February 11, 2013
    Hi Anand, Could you please confirm, can we include Method/Class summary comments into .chm file. thanks, Bhaskar

  • Anonymous
    January 05, 2016
    Anand, Thank you for this post, found it most helpful, now the fun begins...