Automate the creation of an MSDN-style documentation website with Sandcastle (last part)

(This is the last part of a three part series.  You should read the introduction , part one and part two if you haven’t already before reading this post)

By this point, you now have a functioning document website.  How about we take a peek at it?
In order to view the website over the network, you’ll have to create a virtual directory within a website in IIS to point to the output directory where the documentation website is created.  If you want, you can make this the root of a website.  Most likely, you’ll be hosting this documentation website from within another.  For instance, you may host it as a virtual directory within your project’s Sharepoint website.  At my company, we have an internal wiki where we keep various information relating to development.  I decided to host the documentation website as a subdirectory of the wiki website.  The idea is that I can place a link on the wiki sidebar that points to the documentation.  Anyone going to the wiki looking for information on the project can quickly find the link to the docs on the sidebar of the wiki.  And, because it is a virtual directory under the website, I don’t have to create and configure a new website for it within IIS.

I’m not going into depth about configuring IIS here.  I could spend a year covering the various nuances of hosting a webpage.  Frankly, I’d rather code Cobol than do that.  I’ll just highlight some of the more important steps in the process .
I RDP’d into my development server, which hosts TFS and my development wiki.  Within IIS, I added a new virtual directory to my wiki’s website root.  As I said, it isn’t necessary for it to be underneath another website, but I configured it this way so I would not have to worry about managing a separate website.

The virtual directory points to the root of the documentation directory in the file system.  In other words, the Virtual Directory of the website must point to the directory where SHFB copies the website files.  Remember, this is one folder below the network share, as SHFB won’t accept the root of a share as an output directory.

I made sure that the user account that runs the wiki website’s worker process has read and execute rights to the documentation directory.  You’ll need the ability to execute scripts as the documentation website contains .aspx files.
  Next, you have to set the default document.  The reason is because IIS’ default-default-document is, strangely enough “Default.html”, followed by “Default.aspx” and other similar versions.  The default document of the website that FSHB generates is actually “index.aspx”.  So you have to change the default for your virtual directory to match this.  Failing to do so will result in a 404 when browsing the directory.  Once you’ve made this change, browse the virtual directory to make sure everything works.

Nice, isn’t it?
When you create your website, there are a couple different “PresentationStyle” options that can control the look of your website.  Prototype works, I know that.  But there are two others:  hana and vs2005.  Try them and see if they look better for you.  There’s no guarantee they work, of course.  Beta and stuff.

Now that you have a functioning website, its time to automate it during the build.  In a nutshell, you must do the following:

  • Add the SHFB configuration file to your project so that it is copied to the build output folder
  • Add a custom build target to the Team Build to run SHFB (go here for a list of all the different targets in Team Build)

To add the configuration to the project, you’ll need to add it to a specific project within your solution.  You can’t add it as a “Solution Item” because you need it copied to the output folder during a build.  Select a project in your solution that is guaranteed to be around.  I selected one of the core projects that will always be a part of the solution.  Copy the SHFB file from the output where you saved it into your project’s directory and “Add Existing Item” it to a project.  Next, view the properties of the .shfb file and set “Copy to Output Directory” to “Copy Always”.

The last step is to edit the Team Build so that it kicks off SHFB.  You’ll have to edit the team build manually to do this.  Open up Team Explorer (View, Team Explorer).  Expand the node for your project and double click on the Source Control node within Team Explorer to open the Source Control Explorer.  Look for a node in the tree called TeamBuildTypes.  Expand that and open the folder for the Team Build you wish to modify.  Check out TFSBuild.proj for edit and double click on it to open it in the IDE.

This file is a MSBuild script.  It contains markup that describes your build.  Add the following <Target> to the bottom of the file:

<span style="color: blue;">  &lt;/</span><span style="color: #a31515;">ItemGroup</span><span style="color: blue;">&gt;</span>

<span style="color: blue;">    &lt;</span><span style="color: #a31515;">Target</span><span style="color: red;">Name</span><span style="color: blue;">=</span>"<span style="color: blue;">PackageBinaries</span>"<span style="color: blue;">&gt;</span>

<span style="color: blue;">        &lt;!--</span><span style="color: green;"> Build source code docs </span><span style="color: blue;">--&gt;</span>

<span style="color: blue;">        &lt;</span><span style="color: #a31515;">Exec</span><span style="color: red;">Command</span><span style="color: blue;">=</span>"<span style="color: red;">&amp;quot;</span><span style="color: blue;">C:\Program Files\</span>

<span style="color: blue;">EWSoftware\Sandcastle Help File Builder\</span>

<span style="color: blue;">SandcastleBuilderConsole.exe</span><span style="color: red;">&amp;quot;</span>

<span style="color: red;">&amp;quot;</span><span style="color: blue;">$(OutDir)CONFIG.SHFB</span><span style="color: red;">&amp;quot;</span>"<span style="color: blue;"> /&gt;</span>

<span style="color: blue;">    &lt;/</span><span style="color: #a31515;">Target</span><span style="color: blue;">&gt;    </span>

<span style="color: blue;">&lt;/</span><span style="color: #a31515;">Project</span><span style="color: blue;">&gt;</span>

Please note!  This shows the last ItemGroup’s closing tag and the Project’s closing tag for reference only.  DO NOT COPY THEM to the bottom of your build file!  Also note that you must change the name of the configuration file (config.shfb) to the name of the configuration file in your project.

This line “targets” the build during the PackageBinaries phase to execute SHFB.  This “event” happens after all binaries have been built and all tests have been run.  Save your build script and check it back into source control.  If you do not check TFSBuild.proj back in after saving, your changes will not be picked up by Team Build and your website will not be built!

And that’s it!  Go ahead and kick off your Team Build.  Check the website to make sure that it builds correctly.  One note at this point:  If you are logged into the build machine as the build is happening, if any exceptions are thrown you will be asked if you want to debug it.  This can cause the build to hang indefinitely.  So, just to be safe, make sure you’re either logged out of the build machine when this runs or look for the debug dialog if the build is hanging.  If your website doesn’t build properly, check the output directory for a log file.  Our project has six binaries that are built during our Release team build on an Intel Core 2 Duo box running XP.  The whole process takes less than ten minutes.  YMMV.

When the build is complete, go view your website.  Figure out where your docs are lacking.  Go into your code and fix your documentation.  Then kick off the build again and see your changes.  Nice.