Today I'm releasing another small tool that I created for personal use that I believe others might find of use. The tool is the .Net Configuration Section Documentation Generator (more proof that I should not be put in charge of naming things), which does what it says on the tin: it generates documentation for configuration sections defined using .Net's ConfigurationSection class.
Basically, it can generate an XSD schema from a ConfigurationSection, to which you can then add annotations to document the elements and attributes of the section, and then generate an HTML documentation file from that schema. The tool can be used with Microsoft .Net and Mono.
As an example, check out the schema for the documentation generator's own configuration section as generated by the documentation generator, and with added annotations. And finally, the documentation file generated from the annotated schema. This is only a very trivial configuration section, but it gives you an idea of what the output of the documentation generator looks like.
More information and downloads here.
2014-06-05 19:08 UTC
I discovered a minor bug in ConfigurationDocumentationGenerator when handling ConfigurationElementCollections. In the case where an Element or Section contains an ElementCollection, the schema correctly defines the collection type, but doesn't add the reference to it in the container.
I resolved this by adding the following lines to ProcessConfigurationElement:
foreach (var property in properties)
{
...
if (configurationProperty != null && (!collectionKeyOnly || configurationProperty.IsKey))
{
if (property.PropertyType.IsSubclassOf(typeof (ConfigurationElementCollection)))
{
if (configurationProperty.IsDefaultCollection)
{
...
}
else
{
AddComplexType(elements, processedElements, property.PropertyType);
all = GetOrAddChildNode(complexType, Xsd.All);
XElement child = GetOrAddChildNode(all, Xsd.Element, "name", configurationProperty.Name);
child.SetAttributeValue("type", property.PropertyType.Name);
child.SetAttributeValue("minOccurs", configurationProperty.IsRequired ? 1 : 0);
child.SetAttributeValue("maxOccurs", 1);
}
...
}
...
}
This is working for the dozen or so config sections I am using.
Thank you for publishing such a useful tool. Have you considered putting it up on CodePlex or some such?
Comments are closed for this post. Sorry.
Subscribe