Code Example: Reference source code file in project?

Topics: Conceptual Topics, Sandcastle
Jul 2, 2008 at 10:06 AM
I have a C# file in my DocProject that contains some sample code, nicely decorated with comments and compilable.

I am wondering if there is a way of including the content of that file in a <codeExample> section, for example <code language="c#" addres="???"> rather than copy the content to the aml file and mangle the < and > characters into HTML.
Coordinator
Jul 2, 2008 at 1:19 PM
Edited Jul 2, 2008 at 1:21 PM
Hi, 

See the following discussion about the Code Block Component.  I think it also works for conceptual documentation but I don't know for sure.

http://www.codeplex.com/DocProject/Thread/View.aspx?ThreadId=28446

Note that if you're using Visual Studio 2008 then you must add the following line to DocProject's configuration file to be able to add the Code Block Component to the build component stacks via the stack editors accessible from the DocProject Properties window.

  1. Open DocProject's configuration file; commonly, C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config (do not confuse this file with DocProject.exe.config).
  2. Add the following element as a child of the configuration\addin\dependencies element.
<add name="SyntaxComponents" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />

Alternatively, you can just register the component manually in your project's configuration files, found in Help\Presentation\Style\Configuration.

- Dave
Jul 2, 2008 at 2:26 PM
Thanks.

I downloaded the Sandcastle Standalone Build Components, unblocked them (Vista!, I've learned my lesson there) and copied the folder SBComp_v1700 to the Sandcastle ProductionTools folder.

Then I added the following line to the relevant place in C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config (a little different because the DLL is not the same):

      <add name="CustomBuildComponents" assembly="%DXROOT%\ProductionTools\SBComp_v1700\SandcastleBuilder.Components.dll" />

I opened my solution. In the DocProject properties I opened the ellipsis for Help 1.x conceptual build component stack.
I clicked the Add Build Component button.
The available build components does not list anything from SandcastleBuilder.Components.dll
When I click the Browser... button and find SandcastleBuilder.Components.dll I get the error:

"One or more of the selected assemblies could not be inspected due to the following error: Unable to load one or more of the requested types. Retrieve the LoaderExceptions property for more information".

Any ideas?

// Mike


Coordinator
Jul 2, 2008 at 3:19 PM
Hi Mike,

You have to add the SyntaxComponents assembly using the <add /> element as in my example, not the components assembly :)

This is because one of the components (I assume the Code Block Component) references the SyntaxComponents assembly, but since SyntaxComponents is not in the GAC it cannot be resolved automatically by the Framework from within Visual Studio's process (where the DocProject add-in lives).  By adding SyntaxComponents as a dependency, DocProject will handle assembly resolution automatically whenever the Framework needs to load the assembly.  Which, in VS 2008, just so happens to be immediately when the build components assembly is inspected for types since delayed-loading is now apparently an unsupported scenario in VS 2008.

https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=340664
http://davesexton.com/blog/blogs/blog/archive/2007/11/16/docproject-2008-beta-2-assemblyresolve-showstopper.aspx

- Dave
Jul 3, 2008 at 9:37 AM
Thanks Dave.

Your thread incorrectly says that one should use the Standalone Sandcastle Build Components download.

This download does not include either an installer or the SyntaxComponents DLL that you mention. Instead, you have to download the entire Sandcastle Help File Builder Installer. That kind of makes me wonder what value there is in the Standalone Sandcastle Build Components download if it can't actually be used without the full Sandcastle Help File Builder Installer!

This is getting pretty complicated, actually, as it seems that yet further "code providers" need to be downloaded, the SyntaxComponents needs configuring in the build stack, it has to be added at a specific point in the stack (where?), the application requires new <compiler> configuration sections. And then there is the matter of intellisense for the <code> element showing up correctly in DocProject: "source" is not a valid attribute.

<wish>
It strikes me that nearly anyone who is documenting a .Net project is going to want to include code examples and those code examples are best maintained in source code form. Life would be so much easier if DocProject supported this directly rather than having the user fully install a competing product and spend the next week figuring out how the two should work together!
</wish>


Coordinator
Jul 3, 2008 at 11:32 AM
Hi Mike, 

Your thread incorrectly says that one should use the Standalone Sandcastle Build Components download
This download does not include either an installer or the SyntaxComponents DLL that you mention

The download is a zip file that contains all of the custom build components, which should be everything that you need.  There's no installer, so I assume that you can probably unzip the contents anywhere.  SyntaxComponents.dll is a Sandcastle assembly though, so it's already on your computer.  (Look in the ProductionTools folder in the Sandcastle installation directory.)

Instead, you have to download the entire Sandcastle Help File Builder Installer

I don't think so.  Nobody else seems to have had to install the full program just to use the standalone build components in DocProject.  At least nobody mentioned that to me.

That kind of makes me wonder what value there is in the Standalone Sandcastle Build Components download if it can't actually be used without the full Sandcastle Help File Builder Installer

I would have to agree if it were true, although I don't think that your assumption is accurate.

This is getting pretty complicated, actually, as it seems that yet further "code providers" need to be downloaded

I'm not sure what you are referring to by code providers.  Are you attempting to document a Web Site project perhaps?  If so, the limitations are due to the design of Web Site projects in Visual Studio, so there's nothing else that can be done about it other than to use a custom code provider or follow my recommendation and use a Web Application project and/or a class library instead.

the SyntaxComponents needs configuring in the build stack, it has to be added at a specific point in the stack (where?)

The SyntaxComponents.dll assembly does not provide any build components (it probably should have been named SyntaxGenerators.dll).  Although, if you're referring to Sandcastle's SyntaxComponent build component, which exists in BuildComponents.dll in the ProductionTools folder, that's already in the reference stacks as a subcomponent to the first If component.  To add SyntaxComponent to the conceptual stacks you must edit the configuration files manually (Help\Presentation\Style\Configuration\conceptual.helpNx.config).

I guess you could just copy the <component> element for the SyntaxComponent from within the <!-- Generate Syntax --> section of the reference stacks, but I can't say for sure whether that's even required in the first place since I don't know how the code block component works.

You're probably better off asking about this in the SHFB forum.  If you find out what the requirements are to use the code block component in conceptual stacks then feel free to ask me how to perform the necessary tasks to get it working in DocProject.   (Note that getting it to work in DocProject should be exactly the same as the requirements for getting the component to work using Sandcastle by itself, without any automation tool.  So if the components work outside of SHFB and DocProject, then they should also work inside of DocProject as well without any extra effort.)

the application requires new <compiler> configuration sections

Again, I think you're referring to a Web Site project, to which these limitations are inherent.  Some manual configuration, to produce output that may be used by Sandcastle, is required by design in Web Site projects and so is unavoidable unless you use a different project type.

And then there is the matter of intellisense for the <code> element showing up correctly in DocProject: "source" is not a valid attribute

If you're referring to the MAML code element as used in conceptual topics, the list of supported attributes that are shown by IntelliSense are taken from the MAML schemas provided by Sandcastle.

The source attribute, presumably, is an extension to the schemas provided by the code block component.  If you want IntelliSense to be accurate for the custom build components that you're using then you must update the MAML schemas manually.  This is unavoidable since the MAML schemas are provided by Sandcastle, which obviously does not support the various features of custom build components.

Note that I'm working on releasing a preview of my MAML editor within the next week (hopefully by Monday) so issues with IntelliSense for conceptual topics in Visual Studio's XML editor should become a thing of the past.

<wish> [snip]

I agree that being able to pull in code snippets from source code is probably a useful feature of the code block component.  Although, I don't think that you need to install SHFB to get it working; the task of incorporating the component into DocProject projects shouldn't be a difficult one.  The code block component also offers other features, such as code coloring, but frankly I've never seen enough value in code coloring snippets to where I've wanted native support for it in DocProject, and so I hadn't intended on reinventing these features.

Regardless, I'll add this as a feature request and see if I can get something working for the 1.12 release.  My goal will be to have DocProject natively support pulling in code snippets from actual source code files.  (Again, I agree that this seems like a useful feature - especially considering how easy it is to add buildable code directly to DocProjects and DocSites.)  However, I don't plan on adding support for code coloring or any other features of the code block component (if there are any) for this next release.  Maybe I will in a subsequent release though if there's enough of a demand for it.

Thanks for the feedback, 
Dave
Coordinator
Jul 3, 2008 at 11:38 AM
Edited Jul 3, 2008 at 11:38 AM
Created feature request: 

Ability to Pull in Code Snippets from Buildable Source Code
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=17241

- Dave
Jul 3, 2008 at 3:09 PM

The SyntaxComponents assembly is not part of SHFB, it's part of Sandcastle so it isn't distributed by me.  The main problem here seems to be that DocProject is trying to load the assembly in some way that requires extra definitions on its part to handle the dependencies.

You don't need the full SHFB download for the standalone components.  There is no installer for the standalone build components because, well, they are standalone so there's really nothing to "install".  You just unzip it to a location of your choice and edit the sandcastle.config and conceptual.config files to include the components were they need to be.  The paths in the component configurations should point to were you placed them.  There is a help file provided that describes the components and their configurations and where to place them in relation to the other components if doing it by hand.

With SHFB, integration of third-party build components is automatic and is handled at build time via the SandcastleBuilder.components.config file supplied with the components.  DocProject could probably use that to add the component to its config files too.  If you're doing it by hand, you need to edit the configuration files yourself but the default configuration supplied within the component .config file can be used as a starting point.

Eric

Coordinator
Jul 3, 2008 at 3:50 PM
Edited Jul 3, 2008 at 3:52 PM
Hi Eric,

Thanks for the reply.

I think the problem here is actually just a simple misunderstanding.  The SyntaxComponent problem isn't with DocProject, it's with Visual Studio 2008.  In the other thread I linked to my bug report on Microsoft's connect website which explains the details, but basically when you use reflection in VS 2008 to load a type, all assembly references are resolved immediately so delayed-loading is not supported.  Since SyntaxComponent is not located in the VS probe path or the GAC, it's not found and an error occurs.  Registering SyntaxComponents.dll as a dependency in DocProject's configuration file easily fixes the issue since DocProject handles assembly resolution itself for all registered dependencies.

Anyway, that issue only affects using DocProject's build component stack editor to add your components.  They can be added manually to the configuration files without any issues.

- Dave
Jul 4, 2008 at 8:34 AM
Thanks for your extensive help, chaps.

There was indeed a misunderstanding on my part as I was looking for SyntaxComponents.dll in Eric's download.

I should say you have both produced a fine set of tools, by the way!

Dave, colouring of code comments is not an issue for me so a native B&W code snippet importer in DocProject would be an excellent addition. I've been using DocProject for a couple of weeks now and (for a programmer documenting a set of web services) it's the only thing that has been "missing" out of the box.

// Mike
Coordinator
Jul 4, 2008 at 10:13 AM
Edited Jul 4, 2008 at 10:15 AM
Hi Mike,

Thanks.  I'll definitely look into adding the buildable code snippet support for the next release.

- Dave