Tools for tutorial/cookbook style documentation

Question

Do you use any tool for writing tutorial style, or cookbook style documentation? How do you keep it up to date (e.g. changes in output, changes in signatures, changes in command line parameters,.. )? Right now I do everything manually, and it's a pain.

I know the tools for producing reference docs, like Sandcastle and NDoc. That's not what I'm looking for.

To clarify, my dream tool would allow me to write an actual .cs or .fs file like:

//>tutorialtext The PrintCakeReady function allows you to check whether your cake is ready. For example:

//>startcodesnippet

var cake = new ChocolateCake();

cake.PrintCakeReady();

//>endcodesnippet

//>tutorialtext Which produces:

//>outputprevioussnippet

This .cs or .fs file should be compilable - I can include it in my project so that it remains up to date. On the other hand I should be able to produce documentation from it, i.e. to html, which would include the code fragments in some distinctive style, execute them (like in Snippet Compiler, or Linqpad) and include the results in the appropriate place.

The benefits would be huge: I'd detect many incompatibilities in the documentation, it could be refactored, and if I change the output of some function, the documentation would auto-update.

But maybe there's a far simpler approach that gets me 90% there. How do you do it?

EDIT I've found this paper which elaborates on this idea. However, the associated tools are old (2002) and not updated.

Answer 1

In F#, the following approach occurs to me (I have not thought through all the implications):

TutorialText @"Yadda yadda yadda
Blah blah blah"

let snippet = <@ 
    let cake = new Cake()
    cake.PrintWhenReady()
@>

DisplayCode snippet

TutorialText @"Blather"

DisplayOutputOfExecuting snippet

Where the idea is that code snippets are quotations of actual code, which you can print or execute, and the execution of the whole program has the effect of printing out the documentation (rather than an external tool walking the .fs file and pulling out comments to make the doc). Basically I am suggesting authoring an internal DSL in F# for authoring documentation, and leveraging the quotation mechanism to deal with the dual nature of snippets (as both text to print and code to execute). I have no idea how well this will actually work.

Answer 2

Things I know of which are vaguely like what you seem to be looking for (but not for C#):

• Pythons's built-in documentation-and-testing stuff.
• Boost's BoostBook documentation tools go to some lengths to ensure code examples are actually tested.

Answer 3

For what it's worth, I did that for Java:
http://www.agical.com/bumblebee/bumblebee_doc.html

I have no plans to port it to F# (need to learn the language first ;-)), but if you would write a similar tool maybe you could get some inspiration (or the opposite).

Cheers!