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:
- --ext=FILE-EXTENSION is used to change the file extension of generated files from .html to FILE-EXTENSION. This is useful if you want to generate e.g. .aspx files instead of .html files (the default).
- --template=TEMPLATE-FILE specifies an XSLT to use for the layout of all generated files. If not specified, then the XSLT returned by mdoc export-html --default-template is used.
- HTML CSS class names are used throughout the documentation, allowing various elements to be customized by providing an alternate stylesheet. The mdoc export-html man page lists the CSS classes that are used.
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.
blog comments powered by Disqus