Is there a way to link documentation projects?

Topics: Developer Forum
Apr 8, 2012 at 3:31 PM

I've got a VS Solution which contains a Silverlight app, a .NET Framework 4.0 web app hosting WCF services, and a Portable Class Library project used to share items between the other two. 

I can't put them all in the same documentation project, I know ("SHFB(0,0): error BE0070: Differing framework types were detected in the documentation sources (i.e. .NET, Silverlight, Portable).  Due to the different sets of assemblies used, the different frameworks cannot be mixed within the same documentation project.  See the error number topic in the help file for details.") but if I set up separate documentation projects, can I merge them or link between them?  In particular, I'd like to be able to link from the .NET Framework 4.0 docs to the PCL docs; likewise from the Silverlight docs to the PCL docs.

For example, in the PCL projects, there's a ServiceFault class which is created in a WCF service and consumed in the Silverlight app.  So the documentation for the service refers to it.  I can add a reference to the appropriate PCL version of the System.Runtime.Serialization.dll used, configure SHFB to show attributes and I get the attribute in the docs but there's no link, as you'd expect.  Is there anyway to configure things to generate that link automatically?


Coordinator
Apr 8, 2012 at 5:56 PM

You should be able to use the Version Builder plug-in for this.  Basically, you'll create one primary project that contains one of the VS projects plus any conceptual content plus two other projects: one for each of the other VS projects that only contain the project as a documentation source and the appropirate framework settings.  Those will be added to the version builder plug-in's configuration.  It will handle building the other two projects when the primary project is built and merging the API content from all of them into the resulting help file.

Eric

 

Nov 7, 2013 at 2:59 PM
I have a similar problem as SGarratt. The core assemblies are portable class libraries which all other projects use.

I can compile an SHBF project with just the portable classes just fine. But I cannot make the SHBF project for the .NET assemblies compile since they reference the PCL library (even if I did not include those as documentation sources). It does not matter if I include the source as a project or an assembly - which means I cannot create documentation for anything that references a portable class library. Any ideas on how I can resolve this?
Coordinator
Nov 7, 2013 at 3:11 PM
Are you getting an error? If so, what is it?

Eric
Nov 7, 2013 at 3:18 PM
Yes; I am getting the following error:

[C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe]
MRefBuilder (v2.7.4.0)
Copyright c 2006-2013, Microsoft Corporation, All Rights Reserved.
Portions Copyright c 2006-2013, Eric Woodruff, All Rights Reserved.
Info: Loaded 1 assemblies for reflection and 1 dependency assemblies.
MREFBUILDER : error : Unresolved assembly reference: System (System, Version=2.0.5.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e, Retargetable=Yes) required by xxxxx.CoreLib [D:\xxxx\xxxx.Documentation.Client.WPF\Help\Working\GenerateRefInfo.proj]
Last step completed in 00:00:01.1406
Coordinator
Nov 7, 2013 at 11:04 PM
As a workaround, you can probably add the Assembly Binding Redirection plug-in to the project and use the Ignore If Unresolved tab to add the assembly names such as System to ignore them. Classes derived from types in those assemblies will most likely not include any base class members but it should allow the build to continue for the time being.

To fix it properly, I need to extend the binding redirection plug-in to allow specification of an old public key token value so that it would support adding a like-named assembly using a different public key token thus allowing redirection from the other framework to the core framework in use.

Eric
Nov 8, 2013 at 3:50 AM
That works for me, thanks for your help.

Adding an old public token key value would be useful, but shouldn't this be built into the tool? I would think my problem is a pretty common use-case?

Regardless, this is an awesome project - thanks for spending time on it.