How to add a New Language Support to Sandcastle

Topics: Developer Forum, User Forum
Apr 19, 2014 at 7:25 AM
Edited Apr 19, 2014 at 7:33 AM
I'm new to Sandcastle, but excited with its beauty and simplicity.
I want to use it for create documentation for a new native language that is not supported by Sandcastle now. So my question is How I could be incorporated to Sandcastle build process to create documentation?

What exactly I need:
1) Custom API structure in a Help File content, i.e. there is no namespaces, delegates, events and other in my language, but there is global scope methods, variables and so on.
2) Custom syntax highlighting
3) Custom API element description - i.e. method, class, struct
4) I have new API elements that is not present at all in managed languages

How I understand the key thing here is file and it's processing in many many stages (suppose I have strongly need to modify it's structure xsd -file). How could I incorporate there and where exactly I need to do my modifications?
What are the steps I need to accomplish?
For instance:
1) Step 1 - Replace MRefBuilder to your component or skip it with already prepared file.
2) Step 2 - ...
and so on.

Any help is appreciated.
Apr 20, 2014 at 8:40 PM
Sandcastle is geared towards documenting .NET assemblies. However, if you can produce a reflection data file that describes your API it is possible to use the tools to produce a help file. The AjaxDoc plug-in is one example of this. It uses AjaxDoc to generate the reflection data from JavaScript files. If you want to use the existing presentation styles and build components, you will need your reflection data file to follow the schema as currently defined. Making arbitrary changes to its format related to the existing elements and attributes would likely render invalid content unless you rewrote the build components and presentation style processing which would be a much bigger undertaking. You'll find the schema in the %ProgramFiles(x86)%\EWSoftware\Sandcastle Help File Builder\Schemas\Reflection folder that describes all of the current elements that go into the make up of a reflection data file. Adding new elements and attributes to your output based on the custom features of your new language should not be an issue. However, you may need to re-implement various build components and the presentation styles to make use of them.

The lack of namespaces is not an issue. You'd just write everything out as if it were in the global namespace. Note that your projects would have to be updated to have the Namespace Summaries include the global namespace as they exclude it by default. You'd have to write your own syntax generators. There are project templates supplied with the latest release of the SHFB VSPackage that will get you started. Syntax generators are more complex than standard build components so it would be a good idea to look at the code for the existing ones to see how they are actually implemented.

If your presentation style needs are not met by the existing presentation styles, you'll need to implement your own custom presentation style. Again, template projects are provided for that. You will need to be very familiar with XSLT since the core transformation relies heavily on it.

You will need at least one plug-in in order to build your help file using the alternate reflection data file. The code for the AjaxDoc plug-in would be a good place to start since it does something similar in that it bypasses MRefBuilder.

Apr 21, 2014 at 7:15 PM
Thanks for fast reply.
I already modified Coloriser xml file to support custom colorization of my language, and now digging into Syntax Generators. How I figured out, they (Syntax Generators) heavily relies on handling file.
And yes, I have an ability to generate, but I need custom lower level elements analogues to class, struct (and others).
I also need custom api attributes, that is not present in current version of reflection.xsd file.
So, how I could deduce I need to tune reflection.xsd and to tune all other things that is connected to it's handling.
But I have no idea of minimal set of them, what I need to modify to get the result.
Is it covered by creating just a one building plugin, or there is other "black magic"?
And I really sorry for may be stupid question, but what is the presentation styles and where I could find them?

To summarise all what we discused now, the task list for implementing new language support is the following:
1) Create with current reflection.xsd schema.
1.1) If it is not coverd your needs (as in my case), take a copy of reflection.xsd, modify it as needed.
1.2) Create with your schema
2) If you need to custom Colorization of code (like <code> elements) modify highlight.xml (it would nice if we could have a description of all it's elements in the SHFB help)
3) If you need to custom Syntax - create Syntax Generator (could you get some comments on it? I explore existing one to VB and CS but it seems that they are really very sofisticated, or may be I miss something to see that they are not...)
4) To making it together one need to create a plugin (but what sort of plugin? like AjaxDoc?)
5) ... May be I missed something?
Apr 21, 2014 at 11:54 PM
You don't need to update reflection.xsd as none of the tools use it or validate against it. It's more for informational purposes and describes what the tools and presentation styles currently expect and can make use of. If you need to extend it by adding elements and attributes, the tools don't really care and will ignore the extra stuff. It's up to you to extend the build components and presentation styles to make use of that new information where needed.

Unfortunately, the underlying tools, presentation styles stuff, and supporting files were never documented fully by Microsoft. There are some blog posts that cover some of it but most of the information is learned by digging into the various parts. That's why I created the help file builder. It hides those details so that you don't have to know them for general use. Of course, implementing support for a new language requires that you do need to go figure that stuff out. Documenting the underlying tools and file structures is a longer term goal, one I haven't done much with just yet.

Presentation styles take the reflection information and conceptual topics and transform them into HTML. Its a way of separating the layout from the data. Each presentation style is free to format the content as it sees fit. For example, the V2005 and VS2010 styles both produce HTML output but each style is different from the other. The Open XML style produces output that is a Open XML document readable by Word or OpenOffice rather than HTML. You'll find the presentation styles in the .\PresentationStyles folder in the SHFB installation folder.

There are several topics in the SHFB help file related to creating custom build components, plug-ins, presentation styles, and syntax generators. See them for some information to get started. Looking at the existing ones to see how they utilize the existing reflection data file elements is probably the best way to figure out what is needed for the time being. I can answer specific questions about their processing too.

Apr 22, 2014 at 7:06 PM
That's a greate news to hear. Actually I hoped that there is another straighter way to take (like you can spend a LOT of time investigating code and creating your own, or there is a bunch of templates that could bring to result, in 5 minutes), but it is as it is. I definitly post here more detailed questions and my final task list, may be some one is interested in it too.

May be there is an up to date "big picture" of Sandcaste tools and their data-flows diagrams? Especially in what order build components and plugins loaded by SHFB through the MEF.