Creating a Chm build using Sandcastle



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 - http://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 (66)

  1. drohm says:

    Where is the link to download it so we can test it?

  2. gcapnias says:

    Is the CTP version released?

  3. Garry Trinder says:

    Not yet and will come out shortly. I will post a blog as soon as it’s out and thanks for your pateince.

    Anand..

  4. Garry Trinder says:

    Not yet and will come out shortly. I will post a blog as soon as it’s out and thanks for your pateince.

    Anand..

  5. Vimpyboy says:

    Isn´t it going to be a add-in for VS?

    Is it going to have a GUI?

    Thanks,

    Mikael Söderström

  6. Garry Trinder says:

    Mikael – The first CTP release will be a stand-alone release. We plan to have monthly updates and will be adding lots of additional features.

    Yes we plan a VS add-in and a GUI later down the road.

    Anand..

  7. Vimpyboy says:

    Okey, great.

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

  8. Vimpyboy says:

    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?

  9. nuggetboy says:

    Mikael:

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

  10. Garry Trinder says:

    Yes and there is no /out in this step. Did you try the test example provided?

  11. mpietsch says:

    Step 4 is somewhat misleading. Everything typed there goes into one line and there is a pipe (|) before the second XslTransform instruction.

    It definetly is a great tool. I only recently switched production to .net 2.0 and actually considered switching back for lack of proper documentation options.

    I am from Germany and looking forward to a version that will provide localized documentation. In some projects my comments have to be German for various reasons.

  12. Vimpyboy says:

    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.

  13. Vimpyboy says:

    Where am I supposed to implement the comments.xml file?

    I can´t find it in the guide.

  14. Rob Caron says:

    If you’ve always wanted to create MSDN-like documentation for your managed class libraries, you’ll want…

  15. Ashley van Gerven says:

    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

  16. Garry Trinder says:

    Mikael – Looks like you have figures out the comments.xml issue. Thanks for posting a blog with Sandcastle helper. I will create a seperate blog with pointers to your helper.

    Yes as Mikael points in his helper readme

    Replace %XMLCOMMENTS% in sandcastle.config to the path to your XML Comments file (i.e. c:projectsMyAppbincomments.xml).

    The comments.xml in sandcastle.config file can be replaced with any other file name such as foo.xml or multiple xml files with *.xml.

    Anand..

  17. Vimpyboy says:

    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

  18. Garry Trinder says:

    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..

  19. Garry Trinder says:

    Mikael – Not in the example I provided. Internally we construct lot of information into the config file automatically and I will provide some details.

    For those wondering what we are talking about please look at the following section in sandcastle.config file:

    <!– Copy in comments –>

    <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="….ProductionToolsBuildComponentsBuildComponents.dll">

             <index name="comments" value="/doc/members/member" key="@name" cache="100">

               <data files="comments.xml" />

               <data files="C:WINDOWSMicrosoft.NETFrameworkv2.0.50727*.xml" />

             </index>

    The comments.xml in sandcastle.config file can be replaced with any other file name such as foo.xml or multiple xml files with *.xml.

    Anand..

             <copy name="comments" source="*" target="/document/comments" />

    </component>

  20. Vimpyboy says:

    Okey, I get it.

    I will keep experimenting.

    Keep up the good work!

  21. leppie says:

    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… 🙁

  22. Garry Trinder says:

    Leppie,

    The dependencies can be at a separate folder called dependency.

    We invoke MrefBuilder with the /dep switch as below:

    MRefBuilder foo.dll /out:reflection.org /dep:dependency*.dll

    MrefBuilder also takes wildcards like the following:

    MRefBuilder dll*.dll /out:reflection.org /dep:dependency*.dll

    That is, I put all the assemblies I want to reflect over in a directory named dll and tell it to get them from there.

    I have a blog coming out shortly documenting these FAQs and I promise better detailed documentation in a week.

    Anand..

  23. Si vous avez toujours voulu cr&#233;er une documentation comme MSDN pour vos assemblies, vous voudrez s&#251;rement…

  24. It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend….

  25. Aram has a post onhow to build a help file using Sandcastle. The MSBuild extension is not in this CTP

  26. zhlee says:

    oh, My god!

  27. Please see the Sandcastle CTP announcement here. Additionally, Arnand (Sandcastle team PM) has posted…

  28. destinyml says:

    Is it posible to exclude classes from the documentation? Eg. by adding an attribute?

    Thank you

  29. Sandcastle says:

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

  30. 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.

  31. 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.

  32. Smöråkning says:

    Update After installing the August CPT of Sandcastle, you’ll need to update to the latest version of

  33. derekgreer says:

    I doesn’t appear that step 5 will work even with a pipe.  It seems XslTransform requires an input file for the second transform applied.

    Derek

  34. Garry Trinder says:

    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..

  35. 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)

  36. AristonDarmayuda says:

    This tools really need the GUI, to complex steps, confusing, and to much error or misunderstanding running the steps.

  37. Garry Trinder says:

    Ariston,

    Please visit http://www.sandcastledocs.com or http://codeplex.com/Tagging/TagDetail.aspx?TagName=Sandcastle to download the GUI created by customers.

    Anand..

  38. Sandcastle says:

    Sandcastle generates GUID file names for HTM. With the release of November CTP you can generated friendly

  39. CaptNemo says:

    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.

  40. EntitySpaces says:

    Check out our help, way cool

    http://www.entityspaces.net/blog/EntitySpaces152NewSandcastleHelp.aspx

    We used the Gui builder program, works very well.

  41. sumans says:

    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.

  42. CWeiss says:

    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.

  43. lkarafantis says:

    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?

  44. tmaisnam says:

    "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

  45. Sandcastle says:

    In April I blogged about Bertrand Leroy ‘s, cool document extraction tool (ScriprDoc 1.0) that will generate

  46. binni says:

    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?

  47. Anda mungkin sudah membaca tentang SandCastle (gimana ga, tiap buka IDE Visual Studio pasti nongol di

  48. DorothyM says:

    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).

  49. dinahc says:

    I got stuck at step 8.

    When I tried to run the BuildAssembler command from the ProductionTools directory, I got a message that only one xml file could be specified.

    I then copied the sandcastle.config into the ProductionTools directory, but BuildAssembler failed. Following is the relevant part of the stack trace:

    Info: CopyFromIndexComponent: Instantiating component.

    Info: CopyFromIndexComponent: Searching for files that match ‘*.xml’.

    Error: BuildAssembler: An error occured while initializing the build component ‘Microsoft.Ddue.Tools.CopyFromIndexComponent’ in the component assembly ‘C:Program FilesSandcastle\ProductionToolsBuildComponents.dll’. The error message and stack trace follows: System.IO.DirectoryNotFoundException: Could not find a part of the path ‘C:Program FilesSandcastleDataReflection’.

    I don’t find a ..DataReflection subdirectory. Was it supposed to be included with the install package or somehow generated in a previous step?

  50. dinahc says:

    OOPS! I just found the article on generating reflection data. I think this might solve my problem.

  51. dinahc says:

    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"?

  52. Kaizenn says:

    Hi, I just tried using the Help builder for the first time. I have just specified the dlls that I need to document, and also the dependencies. When I build, I get the error

    Error: BuildAssembler: An error occured while initializing the build component ‘Microsoft.Ddue.Tools.CopyFromIndexComponent’ in the component assembly ‘C:Program FilesSandcastleProductionToolsBuildComponents.dll’. The error message and stack trace follows: System.IO.DirectoryNotFoundException: Could not find a part of the path ‘C:Program FilesSandcastleDataCpref_reflection’.

      at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)

      at System.IO.Directory.InternalGetFileDirectoryNames(String path, String userPathOriginal, String searchPattern, Boolean includeFiles, Boolean includeDirs, SearchOption searchOption)

      at System.IO.Directory.GetFiles(String path, String searchPattern, SearchOption searchOption)

      at System.IO.Directory.GetFiles(String path, String searchPattern)

      at Microsoft.Ddue.Tools.IndexedDocumentCache.AddDocuments(String wildcardPath)

      at Microsoft.Ddue.Tools.IndexedDocumentCache.AddDocuments(String baseDirectory, String wildcardPath, Boolean recurse)

      at Microsoft.Ddue.Tools.CopyFromIndexComponent..ctor(BuildAssembler assembler, XPathNavigator configuration)

    I do see a mention of the same problem by dinah. Please help.

  53. izotov says:

    Hi,

    is it possible to avoid protected members being listed in the result?

  54. Prasanna.Samuel says:

    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?

  55. Ready for some documentation for the ATK controls ? To skip my journey to create this , download the

  56. timmischkin says:

    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?

  57. gem says:

    <a href="http://www.youtube.com/watch title="beach sand castle build">Come learn how to build a drip sand castle at the beach</a>  

    http://www.youtube.com/watch

  58. serhio says:

    Oh My God! 12 points to follwo just to transform an generated XML to a CHM file!

  59. Bhaskar says:

    Hi,

    Class's or Method's  /// <summary>  comments were not included in the output .chm file.

    Thanks,

    Bhaskar

  60. Bhaskar says:

    Hi Anand,

    Could you please confirm, can we include Method/Class summary comments into .chm file.

    thanks,

    Bhaskar

  61. surfvideo says:

    Anand,

    Thank you for this post, found it most helpful, now the fun begins…

Skip to main content