How to generate anything usnig SandCastle

[K Viltersten]

In my naive hopefulness, i thought that
there will be a new tool available in
the menu, after i've installed
SandCastle. There's not...

So, here i've been sitting and
XMLamenting the comments all day long,
the fingertips are soar, so is my butt
from all the sitting as well.

Guess what! I need help on this last
step. After i've installed SC, how do
i make it spit out the fine
documentation i'm yearning for?

 

[Anthony Jones]

In my naive hopefulness, i thought that
there will be a new tool available in
the menu, after i've installed
SandCastle. There's not...

So, here i've been sitting and
XMLamenting the comments all day long,
the fingertips are soar, so is my butt
from all the sitting as well.

Guess what! I need help on this last
step. After i've installed SC, how do
i make it spit out the fine
documentation i'm yearning for?

You've installed this:-

http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=9921

?

Have you also got this:-

http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=9848

?

(I've seen other GUIs but I prefer this one).

On the build page of your projects properties you should tick XML
documentation file:
The path should be bin\release\outputAssemblyName.XML

Build a release version of your project.

Fire up SHFB the GUI is reasonably self-explanatory (watch the status bar as
you navigate the UI).

 

[K Viltersten]

In my naive hopefulness, i thought that

http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=9921

Yes, i got this one.

http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=9848

I've got this one now. Thanks!

The problem is that the build fails
due to "Could not find path to HTML
1.x help compiler".

Indeed, the option there says "false"
and no path is specified. On the
other hand, it can find SandCastle,
even though it's not specified by
it's path either.

Help?

(It's probably something elementary
but still a gotcha to me.)

 

[Anthony Jones]

http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=9921

Yes, i got this one.


I've got this one now. Thanks!

The problem is that the build fails
due to "Could not find path to HTML
1.x help compiler".

Indeed, the option there says "false"
and no path is specified. On the
other hand, it can find SandCastle,
even though it's not specified by
it's path either.

Help?

(It's probably something elementary
but still a gotcha to me.)

In order to build CHM files you need hhc.exe. This is part of the MS Help
Workshop:-

http://msdn2.microsoft.com/en-us/library/ms669985.aspx

I would make sure you place specific paths in the path fields in the GUI.
For example if you want to build Help 2x files you'll need the VS 2005 SDK
(the help compilier for 2x files is buried in its
2007.02\VistualStudioIntegration\Archive\HelpIntegration). The problem with
this SDK is that it installs an older version of sandcastle and the DXROOT
env variable to its version.

 

[K Viltersten]

The problem is that the build fails

In order to build CHM files you need
hhc.exe. This is part of the MS Help
Workshop:-
http://msdn2.microsoft.com/en-us/library/ms669985.aspx

I was expecting the documentation to be
created as HTML, actually. Perhaps, i'm
wrong in trying to do so?

CHM files feel a little bit awkward,
sometimes. My preference is HTML.

 

[Anthony Jones]

I was expecting the documentation to be
created as HTML, actually. Perhaps, i'm
wrong in trying to do so?

CHM files feel a little bit awkward,
sometimes. My preference is HTML.

In that case you don't need the SDK or Workshop.

In the build section set HelpFileFormat to WebSite. In the Paths section
set output path to .\Help\ Now when you build you will get a website in
your bin\release\help folder. It SHFB which defines the template for the
web site and it builds a ASPX based site.

Note leave set SdkLinkType set to Msdn and make sure your build machine has
access to the internet. This creates links into the online MSDN library for
all the Framework types, very nice.

I have built a pure HTML version of the site with Sandcastle in the raw but
I wouldn't like to attempt to repeat it.

This tool is still very, very young.