web/app.config Intellisense XSD Transform/Include

Topics: Developer Forum, Project Management Forum
Apr 2, 2007 at 6:31 PM
For my application I have recently created a nice XSD for Visual Studio to use to provide Intellisense when editing a web .config or app.config.

I was thinking it would be great to XSLT transform that file into a format such that it could be picked up and included into my help file so that the XML configuration elements get documented in addition to the ConfigurationSection and ConfigurationElement classes in my code.

Pages Class

<pages> element

I love to see this as a standard SandCastle or SHFB feature.

Short of that, what do you think the best approach would be for integrating that into the SHFB build process?

I can handle the XSLT part to transform the XSD <xs:annotation>'s to some other format, but what is the best approach here?

Should I go straight from XSD to HTML?
This would be easy to integrate into the SHFB build process (as a step to do prior to the build and just have SHFB just include the additional HTML content)

Would it be better to go from XSD to the the same format that the reflected api's are generated as?
I think this would have the advantage of my XSLT being simpler and relying on all that existing Sandcastle goodness to generate the HTML (in the chosen stype - proto or msdn style)
But how would I tie that into the SHFB process? Would I need to get in to more straight Sandcastle nitty-gritty to pull that off?

Any thoughts?


Apr 2, 2007 at 9:43 PM
I've got an item on the To Do list to create some sort of plug-in architechture for the build process so that additional tools can be called at various points during the build process. In the meantime, you can modify one of the build scripts so that your tool runs at some point to generate the necessary files. You could then add them as additional content items to the project so that they get picked up and copied and also included in the table of content. Either GenerateRefInfo.bat or TransformManifest.bat in the .\Templates folder are the choices as they run before additional content is copied. You'll have to generate the HTML as getting Sandcastle to produce HTML would probably require modifications to the actual Sandcastle transformation files plus they aren't associated with a namespace.

Apr 3, 2007 at 1:36 AM
Thanks for the suggestions on where to start.

I like your plugin todo item. It just feels cleaner to 'configure' things in the SHFB project file. I like Sandcastle's modular nature, but editing a series of bat files feels -- icky.

But the bat file starter works to get me started right now.
Thanks again.

May 21, 2007 at 3:08 AM
Any update on the plugin?
May 21, 2007 at 5:04 AM
It's still on the To Do list. No plans to actually implement it just yet as I'm busy with some other stuff.

Feb 7, 2008 at 4:00 AM
any change in status for this?
Feb 7, 2008 at 3:33 PM
The plug-in architecture is in place and several plug-ins have been created. I haven't created a script runner plug-in yet although that is still on the To Do list and may get done soon. However, support for XSL transformation is in place. Any additional content file with a .topic extension will automatically be ran through an XSL transform. Three default transformations are supplied, one for each presentation style. You can also specify your own using the TopicFileTransform project property. See the Additional Content section of the help file for details.

Feb 7, 2008 at 9:12 PM
I will have a look into writting a xsd to doco plugin.