Using Sandcastle Help File Builder with NETMF projects

Archive
1

Now that I’m coordinating the Tinkr Open Source project I wanted to generate the API docs with Sandcastle.
So I downloaded the latest version of SHFB, installed it and added the SHFB project to the solution.
Setting everything up is quite easy if you are not doing it for the 1st time.

Unfortunately support for every single .NET Framework version needs to be built into SHFB. Unsurprisingly NETMF was not included. :frowning:

After a short search in the SHFB issues I found that I’m not the only one with this problem. And one had already made a small step In the right direction to solve it, but got stuck then.
I tried to do the same and it worked for me.
Compilation of the docs could be started, but the references to the NETMF assemblies could not be found.
After a little sneaking around the settings I found a preinstalled plug in to ignore unresolved references. All I needed to do was activating the plug in and adding the NETMF assemblies to it.

Now I can generate the API docs automatically from xml-doc comments in VS :smiley:

Here is a detailed description:

  1. Locate the Frameworks.xml file which is normally located in C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder
    Open it and add the following to the Frameworks element (remember to start editor with admin rights or you can not save)
<Framework Platform=".NETMicroFramework" Version="4.2.0.0" Title=".NETMicroFramework 4.2">
		<AssemblyLocations>
			<Location IsCore="true" Path="%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETMicroFramework\v4.2">
				<AssemblyDetails Filename="MFDpwsClient.dll" Name="MFDpwsClient" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="MFDpwsDevice.dll" Name="MFDpwsDevice" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="MFDpwsExtensions.dll" Name="MFDpwsExtensions" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="MFUpdate.dll" Name="MFUpdate" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="MFWsStack.dll" Name="MFWsStack" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Graphics.dll" Name="Microsoft.SPOT.Graphics" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Hardware.dll" Name="Microsoft.SPOT.Hardware" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Hardware.OneWire.dll" Name="Microsoft.SPOT.Hardware.OneWire" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Hardware.PWM.dll" Name="Microsoft.SPOT.Hardware.PWM" Version="4.2.0.1" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Hardware.SerialPort.dll" Name="Microsoft.SPOT.Hardware.SerialPort" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Hardware.Usb.dll" Name="Microsoft.SPOT.Hardware.Usb" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Ink.dll" Name="Microsoft.SPOT.Ink" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.IO.dll" Name="Microsoft.SPOT.IO" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Native.dll" Name="Microsoft.SPOT.Native" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Net.dll" Name="Microsoft.SPOT.Net" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Net.Security.dll" Name="Microsoft.SPOT.Net.Security" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.RPC.dll" Name="Microsoft.SPOT.RPC" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Security.PKCS11.dll" Name="Microsoft.SPOT.Security.PKCS11" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Time.dll" Name="Microsoft.SPOT.Time" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.TinyCore.dll" Name="Microsoft.SPOT.TinyCore" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Touch.dll" Name="Microsoft.SPOT.Touch" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.SPOT.Update.dll" Name="Microsoft.SPOT.Update" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="Microsoft.VisualBasic.dll" Name="Microsoft.VisualBasic" Version="1.0.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="mscorlib.dll" Name="mscorlib" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.dll" Name="System" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Ftp.dll" Name="System.Ftp" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Http.dll" Name="System.Http" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.IO.dll" Name="System.IO" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Net.Security.dll" Name="System.Net.Security" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Security.dll" Name="System.Security" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Text.RegularExpressions.dll" Name="System.Text.RegularExpressions" Version="0.0.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Xml.dll" Name="System.Xml" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
				<AssemblyDetails Filename="System.Xml.Legacy.dll" Name="System.Xml.Legacy" Version="4.2.0.0" PublicKeyToken="2670f5f21e7f4192"/>
			</Location>
		</AssemblyLocations>
	</Framework>

  1. Restart Visual Studio

  2. Change the Framework version in the help project properties to '.NETMicroFramework 4.2’
    see image 1

  3. Activate the ‘Assembly Build Redirection’ plugin.
    see image 2

  4. Add all NETMF Framework assemblies to the ‘Ignore if Unresolved’ tab
    see image 3

That’s it, now you should be able to generate your api doc for NETMF projects.
To support 4.3 (or 4.1) it should work too.
The PublicKeyTokens can be found in:
"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework.NETMicroFramework\v4.2\RedistList\FrameworkList.xml"
and similar for other versions.

2

SHFB is software wonder, just like Keil’s IDE. Even [em]if [/em]it works, it still takes many minutes to do the job.

Once you get fed up with SHFB, take a look at SubMain / GhostDoc - Painless Help Documentation :wink: Saves lots of time and neurons.

3

I remove the SHFB project from build, and only build it manually (right click → Build) when I want to release a new documentation.
And for Tinkr the latest SHFB version is quite quick.

ReSharper can do part of this too (copy comment from base).
And I know the code better after this.
In any case it has big advantages to write documentation for every method and property manually.
No matter if you do it while coding (as everyone should do) or afterwards (as I do it now with Tinkr.

I found at least 10 bugs while ReSharping and about 5 more while writing xml docs.
Didn’t need to run any tests for this.
And I have just started with the docs.

4

@ Reinhard Ostermeier - Are you aware of the tag?

5

don’t know the tag, but if you mean the feature that missing doc is automatically set to base doc, then I know of it.
unfortunately this does not prevent ReSharper 100%ly from raising warnings.

6

There have been several issues which made SHFB not usable with NETMF projects.
But Eric (main developer), me, and NameOfTheDragon hunted down these issues and extended SHFB to support NETMF 4.2 and 4.3.
Eric wrote that he will make a release containing the fixes and extensions by tomorrow.

1 Like