Detecting changes in documentation

Topics: Features, General Questions, Sandcastle
Jul 8, 2009 at 12:57 AM


What is the best way to detect whether the inputs to docproject/sandcastle have changed - and only continue if there has been some change?

We have a server which invokes docproject with an msbuild command line. The docproject build is triggered when the source code changes, but a source change doesn't always mean a change in the docs, so a way to not run sandcastle if there has been no change affecting documentation would be really convenient.

Any help appreciated,



Jul 8, 2009 at 4:20 AM

Answering to my own post, this is what I propose (though I think it may not necessarily be the 'best' way):

In BuildProcess.cs, I can check in BuildStarting() whether there were any recent changes to the source doc files in svn. If so, then we should rebuild.

In AfterExecuteStep(), when the "Generate versioned reflection data" step has finished running MRefBuilder a few times, I can check the following files for changes since the last doc build:

reflection.xml, toc.xml, manifest.xml, assembler\comments\, and a bunch of .aml files that are autogenerated in a previous step. If there has been any changes, I squirrel copies of the files away to check against next time.

Am I missing any files I should be checking for changes? Do I really need to check toc.xml and manifest.xml? or is reflection.xml sufficient? Are there any hidden gotchas when comparing (timestamps/changing guids)?



Jul 9, 2009 at 1:37 PM

Hi Carl,

That's a good question.

At the office we use Team City.  For any given project I'll set up an additional Team City project to monitor a documentation path that differs from the main source in SVN so that automated builds only occur when I commit changes to the documentation; e.g., modifying a conceptual content file in my DocSite (under the Documentation folder in SVN) will cause a documentation build, but modifying source code under the Source folder in SVN will not.  I keep the VS solution file in an ancestor path of both the Documentation and Source folders so that I can have separate solutions if necessary (e.g., for team members that don't have DocProject installed), but still use project references in my DocSite.  (Documentation solutions will always contain all projects to-be-documented, plus the DocSite.)

However, this setup does not take into account whether XML documentation comments have been added, modified or deleted.  I like your idea to keep track of build files and do a comparison later.  Maybe I could get away with storing the XML documentation files that are generated after each source build and then invoke a documentation build if they have changed from the last time.  The only problem with this approach that I can see is that I use different Team City projects for documentation and source builds, so in the scenario where I modify XML documentation and also modify conceptual content, the documentation may get built twice.

I'll put more thought into this when I get some free time.


Jul 10, 2009 at 3:04 AM


Quick question: In BuildProcess.cs, if I determine that the build need not continue, how do I finish gracefully? If I call System.Environment.Exit(0), and running in Visual Studio, Visual Studio disappears. If I call context.Cancel(), sees it as a failed build. How can I exit gracefully when run from either VS or



Jul 10, 2009 at 4:46 AM

Hi Carl,

Another good question :)

I don't think I considered this usage scenario before.  I'll create a work item and add support in a future release.

For now, does provide some way of ignoring MSBuild errors?

- Dave

Jul 10, 2009 at 4:49 AM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Jul 13, 2009 at 10:43 PM

Just to round off this discussion:

After implementing my suggestion earlier in this discussion, a 'build' of the documentation when there has been no change is about 25-30 seconds (only about 10-15 of which is docproject/sandcastle). If there have been any changes, the time taken to build is about 10 mins. In the end, to determine whether or not to do a full build, I decided to check all of the *.org files, the assembler\Comments\*.xml files, and our autogenerated .aml files. This is in addition to checking whether there were any updates to the svn repo that holds all our non-auto-gen docs.