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

Sandcastle

Documentation compilers for managed class libraries
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:
Posted: Saturday, July 29, 2006 8:12 AM by aram
Filed under:

Attachment(s): build_Sandcastle.txt

Comments

drohm said:

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

George J. Capnias said:

Is the CTP version released?
# July 29, 2006 4:19 AM

aram said:

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

Anand..
# July 29, 2006 10:58 AM

aram said:

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

Anand..
# July 29, 2006 10:58 AM

Jason Haley said:

# July 29, 2006 11:46 AM

Mikael Söderström said:

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

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

aram said:

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

Mikael Söderström said:

Okey, great.

Will there be an SDK so developers can use it in their own applications?
# July 29, 2006 2:45 PM

Mikael Söderström said:

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?
# July 29, 2006 8:02 PM

nuggetboy said:

Mikael:

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

# July 29, 2006 9:38 PM

aram said:

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

Scott Hanselman's Computer Zen said:

# July 30, 2006 12:52 AM

mpietsch said:

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

Mikael Söderström said:

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.
# July 30, 2006 6:39 AM

Mikael Söderström said:

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

I can´t find it in the guide.
# July 30, 2006 8:29 AM

Rob Caron said:

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

Ashley van Gerven said:

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
# July 30, 2006 11:34 AM

aram said:

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..
# July 30, 2006 12:04 PM

Mikael Söderström said:

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
# July 30, 2006 12:21 PM

aram said:

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

aram said:

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>
# July 30, 2006 12:28 PM

Mikael Söderström said:

Okey, I get it.

I will keep experimenting.

Keep up the good work!
# July 30, 2006 12:34 PM

leppie said:

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

aram said:

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

Luc Gauthier's Weblogs said:

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

Jan Schreuder on .Net said:

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

Born 2 Code .NET » Blog Archive » Sandcastle CTP Released! said:

PingBack from http://born2code.net/?p=41
# July 31, 2006 3:23 AM

Andrew Stopford's Weblog said:

Aram has a post onhow to build a help file using Sandcastle. The MSBuild extension is not in this CTP
# July 31, 2006 4:31 AM

Jaros??aw Kowalski » Blog Archive » Automating Sandcastle CTP with NAnt said:

PingBack from http://blog.jkowalski.net/?p=52
# July 31, 2006 5:02 AM

zhlee said:

oh, My god!
# July 31, 2006 9:43 AM

Distribute This said:

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

destinyml said:

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

Thank you
# August 2, 2006 7:34 AM

Sandcastle said:


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

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

PingBack from https://blogs.msdn.com:443/sandcastle/archive/2006/08/06/690260.aspx
# August 6, 2006 4:00 PM

Jan Schreuder on .Net said:

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.
# August 11, 2006 9:02 AM

Jan Schreuder on .Net said:

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.
# August 14, 2006 4:19 PM

Smöråkning said:

Update After installing the August CPT of Sandcastle, you'll need to update to the latest version of
# September 16, 2006 11:39 AM

derekgreer said:

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

aram said:

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

davidhernandez said:

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

AristonDarmayuda said:

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

# October 20, 2006 1:52 PM

aram said:

Ariston,

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

Anand..

# October 20, 2006 6:58 PM

Sandcastle said:

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

# November 11, 2006 10:24 AM

CaptNemo said:

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.

# November 17, 2006 9:55 PM

EntitySpaces said:

Check out our help, way cool

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

We used the Gui builder program, works very well.

# November 22, 2006 10:48 AM

sumans said:

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.

# February 27, 2007 3:54 AM

CWeiss said:

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.

# March 9, 2007 6:54 PM

lkarafantis said:

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?

# March 14, 2007 4:07 PM

tmaisnam said:

"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

# April 25, 2007 10:19 PM

Sandcastle said:

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

# June 28, 2007 3:06 AM

binni said:

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?

# September 3, 2007 6:09 AM

Danni Afasyah said:

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

# September 6, 2007 1:21 AM

DorothyM said:

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

# October 3, 2007 6:40 AM

dinahc said:

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?

# October 18, 2007 6:54 PM

dinahc said:

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

# October 18, 2007 6:59 PM

dinahc said:

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

# October 19, 2007 3:23 AM

Kaizenn said:

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.

# November 23, 2007 7:29 AM

izotov said:

Hi,

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

# December 11, 2007 8:40 AM

Prasanna.Samuel said:

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?

# August 13, 2008 11:38 AM

With Great Power comes Great Response.write("Ability") said:

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

# August 27, 2008 12:07 AM

timmischkin said:

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?

# January 29, 2009 5:09 AM
Anonymous comments are disabled

Page view tracker