Windows Live Alerts
Welcome to MSDN Blogs Sign in | Join | Help

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:
Published Saturday, July 29, 2006 8:12 AM by aram
Filed under:

Attachment(s): build_Sandcastle.txt

Comments

# re: Creating a Chm build using Sandcastle

Where is the link to download it so we can test it?
Saturday, July 29, 2006 3:29 AM by drohm

# re: Creating a Chm build using Sandcastle

Is the CTP version released?
Saturday, July 29, 2006 4:19 AM by George J. Capnias

# re: Creating a Chm build using Sandcastle

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

Anand..
Saturday, July 29, 2006 10:58 AM by aram

# re: Creating a Chm build using Sandcastle

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

Anand..
Saturday, July 29, 2006 10:58 AM by aram

# Interesting Finds: July 29, 2006

Saturday, July 29, 2006 11:46 AM by Jason Haley

# re: Creating a Chm build using Sandcastle

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

Thanks,
Mikael Söderström
Saturday, July 29, 2006 1:31 PM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

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..
Saturday, July 29, 2006 1:54 PM by aram

# re: Creating a Chm build using Sandcastle

Okey, great.

Will there be an SDK so developers can use it in their own applications?
Saturday, July 29, 2006 2:45 PM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

Are you sure that step 4 is correct? I tried it, but nothing happends.

This is what i tries:
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl" /out:"D:\Projects\Applications\TestingSandCastle\WindowsApplication1\bin\Debug\reflection.org" | XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddGuidFilenames.xsl" /out:"D:\Projects\Applications\TestingSandCastle\WindowsApplication1\bin\Debug\reflection.xml"

I also tried...

XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl" /out:"D:\Projects\Applications\TestingSandCastle\WindowsApplication1\bin\Debug\reflection.org"

...which prints the whole xml file.

Is there anything wrong?
Saturday, July 29, 2006 8:02 PM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

Mikael:

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

Saturday, July 29, 2006 9:38 PM by nuggetboy

# re: Creating a Chm build using Sandcastle

Yes and there is no /out in this step. Did you try the test example provided?
Saturday, July 29, 2006 10:50 PM by aram

# Sandcastle - Microsoft CTP of a Help CHM file generator on the tails of the deat

Sunday, July 30, 2006 12:52 AM by Scott Hanselman's Computer Zen

# re: Creating a Chm build using Sandcastle

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.
Sunday, July 30, 2006 5:37 AM by mpietsch

# re: Creating a Chm build using Sandcastle

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.
Sunday, July 30, 2006 6:39 AM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

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

I can´t find it in the guide.
Sunday, July 30, 2006 8:29 AM by Mikael Söderström

# Sandcastle - Documenting Managed Class Libraries

If you've always wanted to create MSDN-like documentation for your managed class libraries, you'll want...
Sunday, July 30, 2006 10:42 AM by Rob Caron

# re: Creating a Chm build using Sandcastle

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
Sunday, July 30, 2006 11:34 AM by Ashley van Gerven

# re: Creating a Chm build using Sandcastle

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:\projects\MyApp\bin\comments.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..
Sunday, July 30, 2006 12:04 PM by aram

# re: Creating a Chm build using Sandcastle

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
Sunday, July 30, 2006 12:21 PM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

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..
Sunday, July 30, 2006 12:22 PM by aram

# re: Creating a Chm build using Sandcastle

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="..\..\ProductionTools\BuildComponents\BuildComponents.dll">
         <index name="comments" value="/doc/members/member" key="@name" cache="100">
           <data files="comments.xml" />
           <data files="C:\WINDOWS\Microsoft.NET\Framework\v2.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>
Sunday, July 30, 2006 12:28 PM by aram

# re: Creating a Chm build using Sandcastle

Okey, I get it.

I will keep experimenting.

Keep up the good work!
Sunday, July 30, 2006 12:34 PM by Mikael Söderström

# re: Creating a Chm build using Sandcastle

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... :(
Sunday, July 30, 2006 12:45 PM by leppie

# re: Creating a Chm build using Sandcastle

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..
Sunday, July 30, 2006 12:51 PM by aram

# SandCastle CTP

Si vous avez toujours voulu cr&#233;er une documentation comme MSDN pour vos assemblies, vous voudrez s&#251;rement...
Sunday, July 30, 2006 1:54 PM by Luc Gauthier's Weblogs

# Generate documentation for .Net 2.0, Sandcastle CTP released

It was due to arrive, and it finally has. Microsoft have released the first CTP of Sandcastle this weekend....
Monday, July 31, 2006 2:14 AM by Jan Schreuder on .Net

# Born 2 Code .NET &raquo; Blog Archive &raquo; Sandcastle CTP Released!

PingBack from http://born2code.net/?p=41
Monday, July 31, 2006 3:23 AM by Born 2 Code .NET » Blog Archive » Sandcastle CTP Released!

# Building a chm using Sandcastle

Aram has a post onhow to build a help file using Sandcastle. The MSBuild extension is not in this CTP
Monday, July 31, 2006 4:31 AM by Andrew Stopford's Weblog

# Jaros??aw Kowalski &raquo; Blog Archive &raquo; Automating Sandcastle CTP with NAnt

PingBack from http://blog.jkowalski.net/?p=52
Monday, July 31, 2006 5:02 AM by Jaros??aw Kowalski » Blog Archive » Automating Sandcastle CTP with NAnt

# re: Creating a Chm build using Sandcastle

oh, My god!
Monday, July 31, 2006 9:43 AM by zhlee

# Microsoft Sandcastle July 2006 CTP Released

Please see the Sandcastle CTP announcement here. Additionally, Arnand (Sandcastle team PM) has posted...
Monday, July 31, 2006 10:20 AM by Distribute This

# re: Creating a Chm build using Sandcastle

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

Thank you
Wednesday, August 02, 2006 7:34 AM by destinyml

# Joe in Iowa – &amp;lt;i&amp;gt;A Sandcastle Scenario:&amp;lt;/i&amp;gt;


This post provides steps to create CHM using Sandcastle. Some of the users have automated these steps....
Sunday, August 06, 2006 3:59 PM by Sandcastle

# Sandcastle : Joe in Iowa ??? A Sandcastle Scenario

PingBack from https://blogs.msdn.com:443/sandcastle/archive/2006/08/06/690260.aspx
Sunday, August 06, 2006 4:00 PM by Sandcastle : Joe in Iowa ??? A Sandcastle Scenario

# Sandcastle, a documentation tool for the .Net 2.0 Framework

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.
Friday, August 11, 2006 9:02 AM by Jan Schreuder on .Net

# Sandcastle, a documentation tool for the .Net 2.0 Framework

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.
Monday, August 14, 2006 4:19 PM by Jan Schreuder on .Net

# MSBuild script for Sandcastle

Update After installing the August CPT of Sandcastle, you'll need to update to the latest version of
Saturday, September 16, 2006 11:39 AM by Smöråkning

# re: Creating a Chm build using Sandcastle

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
Tuesday, September 26, 2006 6:09 PM by derekgreer

# re: Creating a Chm build using Sandcastle

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..
Tuesday, September 26, 2006 7:42 PM by aram

# re: Creating a Chm build using Sandcastle

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)
Wednesday, September 27, 2006 11:58 AM by davidhernandez

# re: Creating a Chm build using Sandcastle

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

Friday, October 20, 2006 1:52 PM by AristonDarmayuda

# re: Creating a Chm build using Sandcastle

Ariston,

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

Anand..

Friday, October 20, 2006 6:58 PM by aram

# Generating frindly HTM file names from Sandcastle

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

Saturday, November 11, 2006 10:24 AM by Sandcastle

# re: Creating a Chm build using Sandcastle

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.

Friday, November 17, 2006 9:55 PM by CaptNemo

# re: Creating a Chm build using Sandcastle

Check out our help, way cool

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

We used the Gui builder program, works very well.

Wednesday, November 22, 2006 10:48 AM by EntitySpaces

# re: Creating a Chm build using Sandcastle

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 Files\Sandcastle\Examples\Sandcastle> ..\..\productionTools\XslTransf

orm ..\..\ProductionTransforms\AddOverloads.xsl reflection.org

XslTransform (v2.2.61208.1447)

Copyright c Microsoft 2005-2006

Specify one input XML input file.

Tuesday, February 27, 2007 3:54 AM by sumans

# re: Creating a Chm build using Sandcastle

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.

Friday, March 09, 2007 6:54 PM by CWeiss

# re: Creating a Chm build using Sandcastle

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?

Wednesday, March 14, 2007 4:07 PM by lkarafantis

# re: Creating a Chm build using Sandcastle

"Specify one input XML input file"

Make sure the XslTRansform commands have the /xsl: argument encloded in "" as in -

XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\TocToChmContents.xsl" toc.xml /out:Output\EnergyWorkbench.hhc

and not

XslTransform /xsl:C:\Program Files\Sandcastle\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\EnergyWorkbench.hhc

Wednesday, April 25, 2007 10:19 PM by tmaisnam

# ScriptDoc 1.0 for extractiong Javascript code comments is now available at Codeplex

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

Thursday, June 28, 2007 3:06 AM by Sandcastle

# re: Creating a Chm build using Sandcastle

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?

Monday, September 03, 2007 6:09 AM by binni

# SandCastle+DocProject=CHMv1+RUNTIME_ERROR

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

Thursday, September 06, 2007 1:21 AM by Danni Afasyah

# re: Step 2

Add the path to csc.exe (most probably C:\WINDOWS\Microsoft.NET\Framework\v2.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).

Wednesday, October 03, 2007 6:40 AM by DorothyM

# Problem with BuildAssembler command in Step 8

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 Files\Sandcastle\\ProductionTools\BuildComponents.dll'. The error message and stack trace follows: System.IO.DirectoryNotFoundException: Could not find a part of the path 'C:\Program Files\Sandcastle\Data\Reflection'.

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

Thursday, October 18, 2007 6:54 PM by dinahc

# RESOLVED--Problem with Build Assembler in Step 8

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

Thursday, October 18, 2007 6:59 PM by dinahc

# Chm on Vista

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

Friday, October 19, 2007 3:23 AM by dinahc

# re: Creating a Chm build using Sandcastle

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 Files\Sandcastle\ProductionTools\BuildComponents.dll'. The error message and stack trace follows: System.IO.DirectoryNotFoundException: Could not find a part of the path 'C:\Program Files\Sandcastle\Data\Cpref_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.

Friday, November 23, 2007 7:29 AM by Kaizenn

# re: Creating a Chm build using Sandcastle

Hi,

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

Tuesday, December 11, 2007 8:40 AM by izotov

# re: Creating a Chm build using Sandcastle

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?

Wednesday, August 13, 2008 11:38 AM by Prasanna.Samuel

# Documentation for the AjaxControlToolkit

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

Wednesday, August 27, 2008 12:07 AM by With Great Power comes Great Response.write("Ability")
Anonymous comments are disabled
 
Page view tracker