DocProject vs Sandcastle Help File Builder GUI

问题:

I have several C# projects along with some internal library components that I'm trying to document together. Sandcastle seems to be the place to go to generate documentation from C#. I would like to know which of the two, DocProject or Sandcastle Help File Builder GUI is better and supports the features I need.

I would like to compile only each projects own part of the document and then have it all integrated together in the end. (i.e. the library components in one documentation project and each project in it's own documentation project, then all of the above in a single root using the Help 2 viewer)

回答1:

I can vouch for Sandcastle Help File Builder. It works really well and you can document any number of assemblies within a Sandcastle Help File Builder project. In theory, you could have a Builder project and generate a doc for each C# project and then have a master Builder project which documents everything.

回答2:

Here are some useful links for Sandcastle based .NET documentation:

Tutorial on Sandcastle

Sandcastle Help File Builder (SHFB)
Tutorial on SHFB

Web Project Documentation
Tutorial on how to document Web Projects (More manual and I believe outdated given previous the link)

MSDN reference for XML Documentation

回答3:

I have not used DocProject but it seems like a product with capabilities comparable to Sandcastle.

I have used Sandcastle and I find it an effective tool. You also need Sandcastle Help File Builder (SHFB) to give you a good front-end, as others have mentioned here. Furthermore, you need Sandcastle Styles for presentation-layer patches to the Sandcastle engine. While all three of these components had a new release in mid-2010, I am postponing upgrading from the 2008 release because of a rendering defect in Firefox 3.6 (documented in the 2010.09.06 entry of this defect report).

I have thoroughly documented my experience with the platform describing that issue and a variety of others that you may need or want to consider in order to produce a tidy, professional documentation set. My article "Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code" was just published on Simple-Talk.com in September 2010; it may save you some time, effort, and agony :-).

回答4:

Doc Project produces more polished docs - when it works - which isn't all the time. It's a much more flakey product.

Sandcastle Help File Builder is solid and gets the job done.