collapse Table of Contents
  1. Customizing mdoc's Static HTML Output - Jonathan Pryor's web log
    1. Customizing mdoc's Static HTML Output

Customizing mdoc's Static HTML Output - Jonathan Pryor's web log

« mdoc XML Schema | Main | Exporting mdoc Repositories to Microsoft XML Documentation »

Customizing mdoc's Static HTML Output

Last time, we wrote documentation for our Demo.dll assembly. What if we want to improve the looks of those docs, e.g. to change the colors or add additional navigation links for site consistency purposes?

mdoc export-html uses three mechanisms to control output:

The XSLT needs to consume an XML document that has the following structure:

<Page>
    <CollectionTitle>Collection Title</CollectionTitle>
    <PageTitle>Page Title</PageTitle>
    <Summary>Page Summary</Summary>
    <Signature>Type Declaration</Signature>
    <Remarks>Type Remarks</Remarks>
    <Members>Type Members</Members>
    <Copyright>Documentation Copyright</Copyright>
</Page>

The contents of each of the //Page/* elements contains HTML or plain text nodes. Specifically:

/Page/CollectionTitle
Contains the Assembly and Namespace name links.
/Page/PageTitle
Contains the type name/description.
/Page/Summary
Contains the type <summary/> documentation.
/Page/Signature
Contains the type signature, e.g. whether it's a struct or class, implemented interfaces, etc.
/Page/Remarks
Contains type-level <remarks/>.
/Page/Members
Contains the documentation for all of the members of the type, including a table for all of the members.
/Page/Copyright
Contains copyright information taken from the mdoc repository, specifically from index.xml's /Overview/Copyright element.

By providing a custom --template XSLT and/or by providing an additional CSS file, you have some degree of control over the resulting documentation.

I'll be the first to admit that this isn't a whole lot of flexibility; there is no control over what CSS class names are used, nor is there any control over what is generated within the /Page//* elements. What this model does allow is for controlling the basic page layout, e.g. to add a site-wide menu system, allowing documentation to be consistent with the rest of the site.

For example, my site uses custom templates to provide a uniform look-and-feel with the rest of their respective sites for the Mono.Fuse and NDesk.Options documentation.

Next time, we'll cover mdoc export-msxdoc.

Posted on 11 Jan 2010 | Path: /development/mono/mdoc/ | Permalink
blog comments powered by Disqus