NDoc3 Extensibility
Both the MSDN and VS.NET documenters support an extensibility model that allows you to define your own tags and control where and how they appear in the documentation. NDoc3 relies heavily on XSLT to generate documentation and the extensibility model is based on XSLT as well.
-
The first step is to add your custom tag to the code comments in your C# files:
[C#]/// <myTag>This is a custom tag</myTag> /// <summary> /// When processed by the VS.NET or MSDN documenters, /// using the stylesheet "extend-ndoc.xslt" as the ExtensibilityStylesheet /// property will result in end-user defined tags being displayed in the /// final help output topics /// </summary> /// <remarks>This is a test of an inline <null/> tag</remarks> public class ABunchOfCustomTags { }
When the compiler generates the /doc summary file, it will include your custom tag in the XML.
-
Next create an XSLT file with templates that control where and how your tag will be displayed:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<xsl:template match="node()" mode="xml-data-island" priority="1">
<MSHelp:Attr Name="TargetOS" Value="Windows"/>
</xsl:template>
<xsl:template match="ndoc" mode="header-section">
<style type="text/css">
.green
{
color:green;
}
</style>
</xsl:template> <xsl:template match="myTag" mode="seealso-section">
<h1 class="green">
<xsl:apply-templates select="./node()" mode="slashdoc"/>
</h1>
</xsl:template>
<xsl:template match="null" mode="slashdoc">
<xsl:text> null reference (Nothing in Visual Basic) </xsl:text>
</xsl:template>
</xsl:stylesheet>
This stylesheet must be valid XSLT markup, and must also include the XSLT namespace.
The templates in this stylesheet need to be written to match the names of your tags. The match attribute is an XPath query that defines the context at which your template will execute. The most common usage is to simply match the name of your custom tag, but it is also possible to change the behavior of your tag based on what sort of code artifact it is associated with.
Note: If you want NDoc3 to perform standard processing of tags within your tags (for example, expanding in-line tags such as <see>) you must include the following within your processing
<xsl:apply-templates select="." mode="slashdoc"/>
The header-section template allows you to specify additional content in the <head> of the generated html. This allows stylesheet authors to define custom css styles or override NDoc3's default styles.
The mode attribute is used to specify where in the documentation your tag will be displayed. There are two types of extensibility tags that can be defined:
- Section Tags - These are block tags that will be rendered in a particular section of the documentation. For a section tag, the mode of the template needs to correspond to a predefined list of section names. Refer to the section topic for a complete list of sections and their descriptions.
- Inline Tags - These are tags that appear inline with text and other tags within a comment. To define an inline tag, the mode of its template should be set to "slashdoc". These templates will then be executed whenever the tag is encountered within a block of text.
If a template matches any of the generic XPath selections: node(), text(), *, or @* you will need to supply a priority attribute on the template with a value greater than 0.5. This forces XSLT to use your templates rather than the default templates that NDoc3 includes for the various extensibility sections.
Remember: XSLT is case sensitive; so both the match pattern and the mode names must be the correct case or your templates will be ignored.
-
Next, set the ExtensibilityStylesheet property of your MSDN or VS.NET project to the path to your stylesheet. When NDoc3 builds the documentation, it will include this stylesheet and display your tags according to the rules you specify in the XSLT templates.
The resulting overview page for this topic will look like:
Example Extensibility Output