How do I create HTML documentation?

Feb 22, 2008 at 5:51 PM
I have been tasked with figuring out how to generate html documentation from XML comments in a VS20005 VB.NET project.

Is it possible to use SandCastle to create HTML documentation from XML?
I can't find any documentaton on SandCastle, but from what I've seen it only creates .CHM help files (using THML Help workshop) .... which is not the same as HTML documentation, right?

If it is possible to create html documentation, then would somebody be kind enough to tell me how this is done?

Thanks,
Dave
Feb 22, 2008 at 6:51 PM
Hi Dave,

Just download SandCastle and SandCastle Help File Builder - Use the SHFB and make it easy for yourself.

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

Create a SHFB project and build it.
In the SHFB you can choose between HelpHtml1, WedSite or HelpHtml2.

You can get more information from the old SandCastle page:
http://www.sandcastledocs.com/

There are examples how to create your own files.

Best regards
--Tony
Editor
Feb 22, 2008 at 8:13 PM
Edited Feb 22, 2008 at 8:15 PM
To add to Tony's comments, see the help file that comes with SHFB. There's a FAQ that covers most of the common questions and issues. There's also a section on Additional Content that describes how you can add additional HTML files to the project to document such things as usage notes, examples, tutorials, etc. You can either add actual HTML files or you can add XML (.topic) files that will be transformed so that they have the same look as the selected presentation style. If you have any questions about its usage, post a message over in the SHFB discussion forum.

Eric
Feb 22, 2008 at 9:00 PM
Hi Dave,


Is it possible to use SandCastle to create HTML documentation from XML?

Yes. Sandcastle generates HTML files, one per help topic, and can easily include your documentation comments.


I can't find any documentaton on SandCastle

See Sandcastle Help for more information about Sandcastle and links to related tools.


but from what I've seen it only creates .CHM help files (using THML Help workshop) .... which is not the same as HTML documentation, right?

Help 1.x (.chm) files are compiled HTML help files. Sandcastle generates HTML and then you have the option of compiling it into a .chm. Sandcastle's output can also be compiled into Help 2.x (.HxS), which is a help collection that can be integrated into Visual Studio's help collections, which can be displayed by pressing F1 to open Document Explorer.


If it is possible to create html documentation, then would somebody be kind enough to tell me how this is done?

To add to Tony and Eric's suggestion, I'd like to also recommend DocProject if you're interested in seamless Visual Studio integration.

- Dave
Feb 22, 2008 at 9:58 PM
Thanks for the feedback - you guys are awesome!


I think this information will help me.

Y'all have my permission to leave work early today and throw back a couple of beers ;-)

Have a nice weekend.