Support for single page layout presentation style

Topics: Developer Forum, User Forum
Oct 11, 2012 at 7:49 AM

Hi

I'm currently outputting my documentation as a web site (vs2010). All works as expected, but I would like the ability to change the default iframing of the pages to a more current MSDN-like style.

I've Googled for a way to do so, but apparently the only way it is possible, is through a forked project, which is not actively being developed (http://code.google.com/p/sandcastle-presentation).

Are there any plans on supporting a single page layout, which more easily can be styled? I've read the other discussions about some legal mumbo jumbo from Microsoft, preventing SHFB from integrating that style, but a single page layout shouldn't be a problem, right?

Otherwise, keep up the great work - it is greatly appreciated!

Sincerely

Kenneth 

Coordinator
Oct 11, 2012 at 4:13 PM
Edited Oct 11, 2012 at 4:19 PM

Anyone can create a presentation style, even one that mimics the MSDN layout, so that's not an issue.  The VS 2010 style from the v2.7.0.0 release relied on a branding package from Visual Studio which I didn't feel could be distributed with Sandcastle so it was copied in by the installer provided you had a copy available.  The latest release has resolved that as I'm getting rid of branding support in favor or purely self-branded content.  The latest release contains some remnants of the branding stuff but just enough to produce the output and no longer relies on the Visual Studio branding package.  The rest of it will be removed as time permits.

In this case, such a style as you are requesting would most likely be strictly for website output since the TOC is effectively on each page.  It would probably require some new build components to figure out the information to include for the TOC part of each page.  Creating a presentation style is no small amout of work so it will take a significiant investment of time.  I'll add it to the To Do list but can't say when it might get done.  If anyone else wants to tackle it, I can certainly merge it in as I did with the VS 2010 style.

Eric

 

Oct 12, 2012 at 9:00 AM

Of course! I didn't even think about the fact, that the different styles would have to be compatible with each output type. I can see that is a bit of a problem.

Wouldn't it be an idea to make it possible to select a build style for each output type? I'm thinking of making the output types more like the build components, and feeding them with the different settings?

I'm aware of the fact that such a change may be very difficult to implement, and would require a great deal of refactoring, but I believe it would make it easier for others to create new types of documentation builds :)

Coordinator
Oct 12, 2012 at 4:17 PM

I've got some plans to make the presentation styles less tightly coupled to the build tools, both Sandcastle and SHFB.  Part of those changes would allow specifying the output types each presentation style supports.  That would allow new styles to target specific output types such as web only.

Eric

 

Jun 30, 2014 at 9:58 AM
Hi guys,

I am a started on SandCaste, and I was asked to change the layout of the output. I was thinking about the new layout of MSDN, but, by the research that I have done, looks not possible...

Any news about this topic EWoodruff?


Thanks,
Marco
Coordinator
Jun 30, 2014 at 4:58 PM
The latest release contains the new VS2013 presentation style that is a closer match to the MSDN content. The website output has been reworked to use a lightweight TOC style similar to MSDN as well. Starting a couple of releases ago, presentation styles were reworked and are now implemented as MEF components as are build components, plug-ins, and syntax generators. This makes it easier to create brand new styles or clone and modify existing ones without the need to modify the SHFB code base. Component project templates are included with the VSPackage to get started. See the related help topics in the SHFB help file for more information.

Eric
Jul 21, 2014 at 6:35 PM
EWoodruff wrote:
Anyone can create a presentation style, ...
...Creating a presentation style is no small amout of work ...
I need to create a new presentation style for our documentation, because we want to use Sandcastle to generate our web service documentation, but all of the existing presentation styles produce library documentation (i.e., the service endpoints, etc., are not documented and all the syntax examples assume a library reference).

Are there any good tutorials or articles that will help me grok the complexity of building a presentation style from scratch? As you mention, it seems to be a daunting task and I'm not finding much assistance on the web.

Thanks!

Ken
Coordinator
Jul 21, 2014 at 8:17 PM
There is a help topic on creating the presentation style component project but detailed documentation on the parts that go into a presentation style such as the content files, XSL transformations, configuration files, etc. hasn't been written yet. What you change or add depends largely on where the source information is located and how you want it presented. For example, if the end point information is part of the data in the reflection information file such as attributes and you just want to include that in the topics, modifying the XSL transformations would be enough. If you wanted to add new topics based on the end point information that would require a new document model transformation as well as changes to the XSL transformations.

If the changes aren't that complicated and mainly involve adding new information to specific topics, a simple build component may be more appropriate rather than implementing an entire presentation style. I can answer more specific questions here if you have them.

Eric
Jul 21, 2014 at 8:36 PM
Thanks for your quick reply!

I've been poring over all the transforms and configs in the vs2013 style, to figure out where I should start... I certainly appreciate the great amount of effort that you must have put into this over the years! There is a lot going on!

I am prepared to put the endpoint information wherever it will be easiest to extract into the documentation. Currently, we're using the UriTemplate parameter on the WebInvokeAttribute to declare the endpoint, so it should be easy enough to get that from reflection... but, it's not part of what Sandcastle collects today. If I create a build component, will that let me use reflection to gather those attributes and add them to the Reflection.xml file? I haven't looked into build components, yet, because I just assumed a presentation style was the direction I needed to go.

Thanks for whatever assistance you can offer... I know you're probably quite busy, and I don't want to intrude too much on your regular workload.

Ken
Coordinator
Jul 22, 2014 at 8:27 PM
Have you enabled the Include Attributes visibility option? If so, the attribute info should be making it through and you should see it in the reflection information file and added to the syntax section on the type/member declaration. As long as it's appearing in the reflection information file, you can use a build component to pull that info out and reformat it if necessary or just let the XSL transformations look for it and do something with it.

Eric