Documenting PostSharp using Sandcastle

  • Article

Recently Gael Fraiteur wrote to me about how he used Sandcastle December CTP to document PostSharp. You can see the documentation generated using Sandcastle at https://doc.postsharp.org//. PostSharp went Beta this weekend, with a new plug-in PostSharp4EntLib.

PostSharp is a post-compiler: an open platform for analysis and transformations of .NET assemblies after compilation. For more details about PostSharp please vist https://www.postsharp.org/. The MSBuild custom tasks for documenting this projects is available at PostSharp SVN (https://svn.sourceforge.net/svnroot/postsharp/trunk/Build/PostSharp.CustomTasks/) and the MSBuild projects at https://svn.sourceforge.net/svnroot/postsharp/trunk/Documentation/

The documentation (see Documentation/ClassRef/ClassRef.proj and Documentation/Documentation.proj on PostSharp SVN) pipeline has the following steps:

1. After the VS2005 presentation XSLT, run a "post-filter" WebFilter.xslt that
(1) add some <meta> tags for search engines
(2) remove scripts (because they break with modern IE security settings)
(3) remove MSHelp:* elements
(4) add google analytics stuff
(5) preprocessings that implement the <inheritdoc/> tag of NDoc 2.
2. Using a find-and-replace, remove all xmlns:* namespace declarations (also for security warnings)
3. Modify presentation.css to remove behaviors (also for security warnings)
4. Modify the TOC generated by sandcastle to insert titles from HTML files ( AddTocTitle.xslt)
5. Split the large TOC into smaller ones (DHtmlXTree.xslt). This is a non-trivial algorithm that computes the weight of tree chunks and choose where to cut -- automatically. An XSLT was used for this task.
6. From the TOC, generate an XML with url-title pairs, the each page's title contains the titles of ancestors (for seach engines to have a good title, not something like 'overview'). -- ChangeTitle.xslt.
7. Use the XML file generated above to change the titles in html pages ( ChangeTitle.xslt).
8. Use a modified version of DHtmlXTree so that it works with static files (very minor changes).
9. Deploy on a web server as static files (absolutely no server-side script).

The trick is to use two MSBuild tasks that allows to export and import items + metadata to XML, then to have an MSBuild task to execute XSLT with parameters taken from MSBuild metadata. Finally use AltovaXML for XSLT2.

Hope this helps.