SHFB "vs" DocProject

Jun 8, 2009 at 5:39 PM

Hello.

I'm a bit confused about existing two tools: SHFB and DocProject. I understand they're developed by different authors. And I can understand SHFB is standalone app and DocProject if a VS's package with MSBuild integrating. It's obvious. But I read SHFB is going to integrate with VS.

I'd very appreciate for some clarifications about what's the conceptual difference between them, if ever.

Thanks in advance!

Coordinator
Jun 8, 2009 at 9:39 PM

SHFB is currently a standalone tool for Sandcastle and that will continue to be supported.  The standalone version also works with and is included in SharpDevelop.  The latest release uses an MSBuild-based project file format.  This provides future support for Visual Studio integration but also opens it up to extensibility in the standalone version and allows for better integration with other build tools and systems.  I've had several requests to provide Visual Studio integration.  A lot of people prefer it since they manage their other projects within Visual Studio so it's natural  to want the documentation tool to work within the same framework and to add the documentation project to the containing solution file.  Visual Studio will also provide a lot of supporting infrastructure that I won't have to duplicate going forward (better editor support for the MAML and other document files, integration with source control, etc).

Featurewise, the two are fairly close but SHFB was written from the start to be a replacement for NDoc since that's what I used to use.  It provides the same set of features as the old NDoc as well as several enhancements and improvements.  I've also tried to make it as simple as possible to use.  Setting the main project properties is done via a single, common property grid, I find the API filter in SHFB more intuitive to use, and the build component and plug-in support is automatic so that you don't have to mess about with the configuration files manually.  I believe plug-in support is unique to SHFB.  While you can write code that runs in the build in DocProject, I don't think it offers the level or ease of extensibility that SHFB does.  One major difference between SHFB and DocProject is that SHFB is written to work with Sandcastle out of the box with minimal work needed on your part to set up the project and produce a help file.  It doesn't have to make a clone of the existing Sandcastle transformation and configuration files and import them into each and every project.  This reduces clutter in the project and as each new release of Sandcastle comes out, you don't have to update or modify those Sandcastle-related project files.  It just works.  One limitation with this approach is that you can't currently override the Sandcastle resource items such as descriptive text for the topics but I've got an open work item to support that in a future release.  Again, that will be handled via a separate content file with an associated editor.  The file will be merged at build time to override the Sandcastle items automatically so, again, no need to import or alter Sandcastle files when a new version of it comes out.

Eric

 

Jun 9, 2009 at 3:54 PM
Edited Jun 9, 2009 at 5:15 PM

Eric, thanks for detailed answer! I got you as SHFB is trying to isolate me from sandcastle at all.

I'm considering moving all my documentation into wiki (confluence). So I'd like reference documentation (produced from source code's comments) to move also. My final goal to have one online source (wiki) for all documentation (and an ability to export to offline chm, but it's another big story).

Do you have any idea is it possible to do with sandcastle and/or SHFB ? Specifically I need to produce wiki markup instead of html.

 

Coordinator
Jun 9, 2009 at 8:24 PM

In order to alter the HTML generated by Sandcastle to include the stuff to support the wiki, you'd have to clone one of the existing presentation style folders and alter the XSL transformations to include the extra stuff.  SHFB supports customized version of the presentation styles.  If you create your own styles, place the folders in the same location as the default styles (C:\Program Files\Sandcastle\Presentation) and the help file builder will detect them automatically and let you select them in the project. Be sure to include one of the default style names in your folder name (Prototype, Hana, VS2005) as certain build steps are performed differently based on the selected style and this will be the hint that the help file builder uses to determine what action to take.

Eric