Conceptual Document from API Reference?

Topics: Developer Forum
Jan 31, 2013 at 2:06 PM
Here's my challenge - I need to generate conceptual documentation (TOC and topics) from the reflection data. I need a custom TOC, not grouped by namespace, but based on the reflection data. For topics, I need to provide blocks of text/html and insert classes and properties name from the reflection data in appropriate places.

What's the best approach to do this? At what point in the process do I need to hook up any customization?

Jan 31, 2013 at 3:15 PM
You'll need to create a custom presentation style. As far as the TOC is concerned, you'll need to create a custom document model transformation that creates entries for list pages and overloads etc. in the reflection data like the existing styles do and a TOC transformation that groups the topics in the manner you want for the TOC. The custom presentation style definition file will let you specify the transformations to use and the other presentation style items so, provided you can create the XSL transformations and the other presentation style related files, SHFB will let you choose it as an option once you place the presentation style files in the proper location.

See the Custom Presentation Style Definition File and the related walkthrough topics in the SHFB help file for more information. Note that I can't provide help on creating the actual presentation style as that's a lot of work. The best I can suggest there is study the existing ones to see how they are put together. It might help to clone one of the existing styles and try modifying it to suit your needs to start.

Jan 31, 2013 at 3:57 PM
Thank you Eric.

I did start down this route, but I'm struggling as I'm not sure what the XML looks like, both source and target... I was looking at build components - do you think that's a viable option? My C# skills are far better than my XSL ones, so would be my preferred way...
Jan 31, 2013 at 7:37 PM
Some build components copy in reflection data and comment information, others work with specific elements to transform them in some manner such as the conceptual and reference link components. The TransformComponent takes the reflection and comment info and runs it through the presentation style XSL transformations to generate the HTML. Anything's possible so I suppose if you had the time and inclination you could write a build component that stood in for the XSL transformations. It may not be the most effective way to do it though given the amount of work the transformations do. You'd have to have the equivalent handling for all of the various templates. XSL also has the advantage of being modifiable and extensible without rebuilding any code.

I think you've seen it, but if not, there's an article on CodeProject for creating custom build components. Part of it describes how to use the DisplayComponent to see the content of the document as it moves through the BuildAssembler pipeline. You can use that to get an idea of what the XML looks like at various points both before and after a component has processed it.