Something which I forgot to mention in yesterday’s post was that SandCastle can create a website for your API.
When executing the example included within the CTP, in the output folder there is a subfolder called HTML. However, this isn’t very useful as it is simply all the pages which are later compiled in the CHM. However, Sandcastle Help File Builder (SHFB) has an excellent feature, where it takes this output and actually makes it useful.
I have been nice and uploaded the example which SHFB outputs to here with the ASP.net output here. The project I used was different to the previous post as SHFB couldn’t import the example, required a real solution file but its more to demonstrate something.
Just to summarise, SHFB can use the Html outputted from Sandcastle, to convert it into a website which can be uploaded onto a site.
How to use ASP.net to create a ‘nice’ API website
I am now going to go over the process of creating a website based on the output from SHFB and make it look how you want, this could then be incorporated into your own documentation site.
The first thing I did was create a new ASP.net Ajax enabled C# based website. I then copied the following files into the solution.
- html folder
- icons folder
- scripts folder
- styles folder
These are all the files I will be using, if you want other items for different requirements you can include them as well. The most important files, are the folders which Sandcastle outputs and WebTOC.xml which SHFB generates.
From this, we can now generate the documentation site based on your own requirements. I simply processed the WebTOC xml file, created a TreeNode for each item, using the Value property for the URL of the related HTML page. After adding all of them to the TreeView, I hooked into the SelectedNodeChanged event on the TreeView so when a item was clicked, I could load up the related page.
To display the page, I used an embedded iFrame, however to be able to set the URL of the iFrame from the code behind, I had to manually create the HTML for an iFrame within the code-behind and set it to the Text property of a Literal control on the page.
To make the whole thing a bit more pleasing for the user, I wrapped everything in a UpdatePanel and set the UpdateMode to Conditional.
That’s it, very simple once you have the XML processed into the navigation control. With the HTML and the WebTOC.xml are left as loose files so an automated process could simply replace these from a newly created output and the site would automatically update. While my example might not look ‘better’, it was move to prove a point that it could be done.
Note, full credit goes to Eric Woodruff for creating SHFB and the code for the original example. Visit Sandcastle Help File Builder