Version

This page represents information about version 0.3 of FwDocGen, the first publically available version of FwDocGen.

Download

Get it from the FwContrib workspace on SourceForge.

And you can get there by clicking here

Authorship

CraigAndera

Status

Part of the FwContrib workspace on SourceForge.

Relationship With WikiClassPages

I'm aware of the major overlap this tool has with WikiClassPages. To explain, here is part of an email conversation between me and RyanLaNeve:

One of the things that I find most useful about FlexWiki is its ability to email me a WikiNewsletter that highlights the changes that have been made recently. I don't know if you saw, but I made this a fair amount more powerful by adding the capability to specify a wildcard in the topic list, as well as the ability to exclude certain pages.

Our plan is to generate documentation for our classes from the XML doc files that the C# compiler generates. I don't particularly care about how we do this, and your behavior would be a great option...except for the fact that it won't give us diffs. FlexWiki operates by comparing the WikiText in the page itself...which is always the same if we use your WikiBehavior.

The alternative that I've come up with is - as part of our build process - to use FwSync to download all the exisiting documentation, overwrite the docs with docs generated from the new build, and then to upload the changed files (FwSync will compare the "before" and "after" files, and only upload those that have actually changed). There are some intricacies around how to name the pages, but that's the basic idea.

Overview

The basic idea is to use C# XMLDoc comments to emit an XML file describing the classes and interfaces in the build. Then we'd validate them against a schema to ensure that required extra elements are present, transform them to WikiText, and upload them to the wiki site via the editing web service.

The major goals of this effort are:

• To provide a convenient mechanism for viewing both the current and historical versions of documentation.
• To provide a convenient way to get periodic diffs (via a WikiNewsletter)
• To provide a convenient way to make comments on documentation

Non-goals of this effort are:

What's the difference between a goal and a non-goal?

• To provide linkage to issue tracking software.
• To provide a convenient way to alter the docs on the wiki and have those changes automatically reflected in the source.
• To provide a convenient way to view all of the docs at a particular point in time, or for a particular build. Individual doc pages can have their history viewed in the usual FlexWiki way, but supporting a mechanism to view all docs at a particular point in time is beyond the scope of this effort.

Implementation

The tool runs a series of XSLT-based transforms over the output of the NDoc XML documenter. These transforms will create a series of .wiki pages that will have names like:

ClassPage1b32cfh

ClassPageAq1234b

MethodPageA1324a

NamespacePage347abq

and so on. The first part of the name identifies what sort of documentation page it is, and the last bit is a "uniquifier". While it would be nice for linking purposes to be able to use the name of the class or the namespace as the name of the page, this has the problem that the period is interpreted specially by FlexWiki. Plus, unqualified class names are not unique, and qualified class names like "Big.Long.Complicated.Namespace.Classname, Big.Long.Complicated.Assembly.name" are really long, and therefore not particularly useful as a linking mechanism.

The uniquifier at the end will be generated based on a hash of the fully qualified name of the thing we're documenting (class, namespace, method, etc.). By using a hash like this, we can guarantee that the page will always have the same name across different builds of the documentation.

Dependencies

FwDocGen operates on the output of the NDoc tool, which is available at http://ndoc.sourceforge.net . You must select "XML" as the NDoc output mode.

The reason for using NDoc is that is performs a lot of useful pre-processing that FwDocGen would have had to re-implement. Since it is itself freeware, it doesn't seem an unreasonable burden to require it.

Mechanics

The way I see this working in a build is as follows:

1. fwsync init and update to get a copy of the current docs from the server.
2. Visit all the pages and replace their content with "This documentation is invalid. The class, method or namespace may have been renamed, deleted, or altered."
3. Generate the input to FwDocGen using NDoc.
4. Generate the wiki documentation over the top of these files.
5. Upload files that have changed (fwsync uses a hash of file contents to determine whether a file has changed, so if the same contents get written that were originally there, no upload happens).

This should result in a WikiNewsletter with that includes diffs of only the files that have changed.

There is basic support for each page to include a link to a comments page that will appear in a different namespace. Putting it in a different namespace makes it easier to whip through and obsolete all the actual documentation pages. The { { link } } syntax should make it easy to actually includes the contents of the comment page on the documentation page.

Usage

If you simply type

 fwdocgen 

from the command line, you will get a message telling you how to use FwDocGen. Here is what it says:

  fwdocgen Version 0.3.1722.5808 Copyright (c) 2004 Craig Andera candera@develop.com
  Error: /docdir argument is required when /writeonly is not specified


  fwdocgen /docdir <docdir> /docns <docns> /commentdir <commentdir>
      /commentns <commentns> [ /generator <generator> ] [ /verbose ] <input>


  fwdocgen /writeonly [ /templatedir <templatedir> ]




  /docdir       Specifies the directory to which to output documentation files
  /docns        Specifies the FlexWiki namespace to use for doc files
  /commentdir   Specifies the directory to which to output comments files
  /commentns    Specifies the FlexWiki namespace to use for comment files.
  /generator    Optional. If present, specifies the XSLT that will be run
                to generate the script that will drive the generation process.
                If not present, the default transform is used.
  /verbose      Print extra debugging information to the console. Note: this
                produces a *lot* of extra info.
  /writeonly    Specifies that rather than generating documentation, the
                program should dump the default set of XSLT templates to
                the <templatedir> (if specified) or the current directory
                (if templatedir is not specified). If this parameter is
                specified, all other parameters are optional.
  /templatedir  Optional. If not specified, the current directory will be used.


  <input>       An ndoc-generated XML file containing the classes, namespaces,
                methods, etc. for which you are generation documentation.
                Not required when /writeonly is specified.
  <generator>   The relative or absolute path to the XSLT that will be run
                against the input document to create the script that will
                drive the generation process

Note that you must either specify the /writeonly switch or all of the /docdir, /docns, /commentdir, and /commentns switches. The /templatedir and /generator switches are optional.

Modes

FwDocGen operates in one of two modes. When the /writeonly switch is not present, it generates wiki documentation pages. When the /writeonly switch is present, it merely spits out the default XSLT template it uses to generate documentation. The idea is for these to provide a useful starting point for custom transforms, which can be specified using the /generator option (see "Providing Custom Templates" below).

Providing Custom Templates

FwDocGen provides a built-in transforms for generating a reasonable set of documentation pages. (Well, reasonable in that it works - the output itself sucks pretty bad right now. The default template will be improved in future releases.) This template can be written out to disk using the /writeonly switch. It can then be modified and used to generate new documentation. Simply specify the template you'd like to use with the /generator parameter when you generate documentation with FwDocGen.

Examples of Output

None yet. At some point I'd like to run FwDocGen over the FlexWiki assemblies and post the resulting pages on this wiki somewhere.

Issues and Questions

• If we generate 100 pages, and only three of them have changed, will that interfere with our ability to view changes easily?
• Not a problem: FwSync uses an MD5 hash to detect file changes, so even if we overwrite a file, as long as the contents are identical, no problem.
• How can we view changes in the first place? We can visit all pages, but is that really what we want to do?
• Not a problem: since FwSync will only upload changed pages, either RecentChanges, the RSS feed, or a WikiNewsletter can be used to track just the changes.
• Can I include (using the double-curly syntax) things across namespaces?
• Yes.
• If I include the comment pages from another namespace, and someone changes the comment, does that affect the diffs?
• No - changes in the included page are not considered changes to the page itself.
• If I use a WikiBehavior to generate content on a page, how does that affect diffs?
• The same way - you have to make literal change to trigger the email - a change in the generated content does not trigger an email. And diffs in the generated content are not shown.
• Is there a convenient way to tag comments with the version of the page we're commenting on? Might be nice so you can see if the comment was made on a version of the page that has since been updated.
• Can we customize the template with some additional information like Test Status, Development Status, etc?
• Hmm. The NDoc XML generator looks like it might do most of the work. Add in some XSLT transformations and that could be most of it. Needs more investigation.
• This totally seems like the way to go. NDoc has a command-line option, which makes it perfect for integrating into build processes. I will proceed with the assumption that the input to FwDocGen is the output from an NDoc XML generation run.

Questions, Issues, etc.

Bugs and feature requests can be logged here or at the FwContrib project page .

History

Released version 0.3.1812.6145

2004-05-12

• Added hidden /debug switch to allow attach to debugger from command line
• Bumped version to 0.3
• Augmented build script to enable automated release
• Added RegexMatch function to XSLT helper class
• Fixed problem where files that were overwritten were not being truncated * Massive overhaul of XSLT - many improvements to output

Internal Version

2004-04-29

• Completely redid transforms, ditching individual transforms in favor of single transform that spews all the files.
• Added /verbose switch
• Updated unit tests
• Added support for structures, interfaces, enumerations, and events

2004-04-21

• Initial add to FwContrib on SourceForge