Share via

Genereating Website for API documentation using Sandcastle

  • Article

 

In this blog on generating builds using Powershell, I provided details on generating a single command wrapper to build CHM and HxS files regardless of where the source assemblies and comments are located. This powershell script provided the following features:

  • Allows the build options to be read from a configuration file. Options specified on the command line override options defined in the configuration file.
  • Handles any number of target assemblies and comment files, including globbing.
  • Handles any number of dependencies.
  • Should work with .NET 2.0, 3.0, and 3.5.
  • Supports vs2005, prototype, and Hana presentation styles.
  • Provides hooks to add new presentation styles in the future, including user defined styles, and user defined function overrides.
  • The script is written for PowerShell 1.0.

Prerequisites

The build script has the following dependencies:

  • Latest release of Sandcastle from https://www.codeplex.com/sandcastle.
  • The DxRoot environment variable must point to the root of the Sandcastle installation.
  • To make it easier for the user, the PATH environment variable should contain the …/ProductionTools folder, which contains the scbuild.ps1 script.
  • .NET 2.0 for Sandcastle.
  • PowerShell 1.0, with the execution policy set to RemoteSigned or Unrestricted. [Note: In a future release we could Authenticode sign the script to make this unnecessary.]
  • hhc.exe to compile CHM files.
  • Hxcomp.exe to compile HxS files.

 

Running the Script

The scbuild.ps1 script can now be used to build a website, in addition to .chm and .hxs files. To build a website use the –BuildWebsite option. For example, to build a website with API documentation for an assembly named test.dll, with comments in comments.xml, use the following command:

 

                scbuild –framework 2.0 –sources test.dll,comments.xml –BuildWebsite

 

The build result will be in test website. You can use the –name option to specify an output location and root name for the website.

 

Currently scbuild supports only the default presentation style: -style vs2005. Future versions may support other output styles.

 

The output from scbuild is designed to be integrated into an existing website. The master page, web.config file, and style sheet in the output directory are intended as a starting point for further customization. You will probably want to keep the contents of the icons and styles directories however, because they are used to give the generated API topics the vs2005 look-and-feel. All JavaScript functionality was disabled in this version, to minimize conflicts with the website the reference topics will be merged into.

 

Also note the contents of the web.config file, specifically the <globalization/> element. Make sure to copy the sample definition to your own website, to ensure that non breaking spaces get displayed properly.

 

The “api” directory contains one ASP.NET content file for each topic and a sitemap that you can merge into the sitemap of an existing website, as shown in the example. At runtime, the sample master page uses a tree view to display the sitemap and a simple content placeholder to display the topics.

 

To merge the output into your own website, you can copy the api, icons, and styles directories to the target website and include the sitemap into the master sitemap file as appropriate. Or you can use the –WebTemplate option to specify a user defined template that will be copied to the output directory, instead of the Sandcastle sample.

 

If you want to use the generated sitemap, include the following reference to the API topics in your own sitemap:

 

      <siteMapNode siteMapFile="api/web.sitemap"/>

 

Further customization is possible through the –WebBuildConfig option, to specify a custom BuildAssembler config file.

 

For more information, please refer to the header of the scbuild.ps1 script, which shows a list of all available build options and short descriptions. Hope this helps.

 

Anand..

Comments

  • Anonymous
    January 16, 2008
    A new release of Spring.NET which brings AOP to .NETA new version of Sandcastle is outSun aquires MySQLApocolyptic