Use DocProject for this?

Topics: Conceptual Topics, Sandcastle
May 14, 2008 at 10:13 PM
I've been working through the capabilities of Sandcastle, and your add-on, and the Conceptual stuff looks promising for some basic program documentation. What I'm looking for is something that will be close to as simple as comments in the source file that are typically placed in one file for the application. Sometimes this would just be a text file that's part of the project. This is the kind of stuff we currently include:

System: system_name
Author: author_name
Creation date: _date_
Purpose: _purpose_
Other stuff:
Build      Date         Who     Comment  mm-dd-yy  xyz      Fixed the bladdy blah (might have a bug tracking reference here)  mm-dd-yy  etc      ......

It seems like the Conceptual addition to Sandcastle would be useful, even though our primary usages wouldn't be help files. But the convenience of having this kind of documentation along with the internally generated class and method documentation makes sense.

The issue, though, is that trying to do this simple kind of documentation is way more complicated when it comes to input, because of the XML requirements, the Sandcastle requirements, etc. If I could get this down to a manageable level, we might be able to pull this off.

How complicated would this be within DocProject? How would you go about doing it?

Thanks for the advice.
May 15, 2008 at 1:07 AM

Just to be clear, are you looking for a way to automatically generate one or more help topics based on information from a flat file (e.g., system, author, change log)?

Please let me know if I'm completely off base here ;)

- Dave
May 16, 2008 at 5:07 PM
Hi Dave.

The information would be in a separate (flat) file. Isn't that where other Conceptual documentation would go? The goals:

1. It would be almost as simple as the example given above for the programmer to enter.
2. It would format nicely for display (and print).
3. (Ideally) It could become part of the overall documentation on a project/solution, to go with the internal documentation generated with the triple-slash capability in the code.

As to goal #1, ideally the input process would hide as much of the details of the XML as possible. I think that's what I'm really interested in understanding about DocProject.

Did that help?

- jim
May 16, 2008 at 11:44 PM
Hi Jim, 

IMO, you should create a MAML topic(s) and allow your developers to add information directly to that file (MAML is an XML format used by conceptual builds in Sandcastle and DocProject).  Or to make things more flexible, and possibly easier for your developers, they can add information to a separate XML file(s) and then you can run a custom XSL transformation to create your conceptual help topic(s) in MAML.  Either way, using XML will allow you to create a GUI to edit this stuff, which in the end, may be even simpler than using notepad and a flat file.  (More on adding a UI to DocProject below.)

If you must stick with a delimited flat file format instead, then you could create a command-line tool that converts your text file format into one of the MAML document types (probably the general Conceptual schema will do), and simply add it as a step in the build process.  There are two ways to insert a build step.  The first is to use your DocProject's or DocSite's Build Process Component to insert a dynamic build step.  The second, more robust way, is to create a custom Build Engine Provider that derives from the Sandcastle Build Engine Provider.  Check out the following topics for more information.

Build Process, Build Process Component

Creating a Build Engine Provider

Also with a custom build engine provider you can add a GUI into DocProject, as mentioned above.  The tutorial shows you how to add new project options, which are displayed in a property grid control in the DocProject Properties window.  Adding a new UI is as simple as using various ComponentModel attributes on your property to describe it for display purposes and to attach a WinForm editor.  Check out the SandcastleProjectOptions class in the DaveSexton.DocProject.Sandcastle project for working examples.

If you're only generating one MAML topic dynamically, to get it into the TOC you can create an empty placeholder topic in the same way that you would create a normal MAML topic via Topic Explorer.  Your custom build step should replace the placeholder topic with the dynamically-generated version at some point before the Build Assembler {concetual.help1x.config} step is executed.  To make things easier, you could insert your build step as the first step of the process.

Otherwise, if you're generating multiple MAML topics dynamically, you'll have to create them in your project's Help\Topics folder and then update the project's Help\Settings\topics.xml file, which defines the TOC.  Updating topics.xml can be done manually or dynamically during the build process by adding an additional build step.

Have I answered your question?

- Dave