The NewtonSoft.Json.xml file has references to a file that is not shipped with it which results in Sandcastle breaking

Question

I am trying to reference Newtonsoft.Json.xml as part of documenting my own code that is dependent on it. When I try and compile my help file in Sandcastle I get the following error:

BuildAssembler : error :  [...\BuildTopics.proj]
BuildAssembler : error : CodeBlockComponent: [N:Newtonsoft.Json] Unable to load source file '...\Visual Studio 2017\Projects\CBUSAlexa\trunk\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs'
Error: Could not find a part of the path '...src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs'. [...\BuildTopics.proj]

(some paths have been obfuscated)

Looking in the Newtonsoft.Json.Xml I see:

        <member name="T:Newtonsoft.Json.DefaultValueHandling">
            <summary>
            Specifies default value handling options for the <see cref="T:Newtonsoft.Json.JsonSerializer"/>.
            </summary>
            <example>
              <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingObject" title="DefaultValueHandling Class" />
              <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingExample" title="DefaultValueHandling Ignore Example" />
            </example>
        </member>

This code is not shipped as part of the Json.NET install and hence the src path is missing (which makes sense as they are tests) and yet Sandcastle should not just abandon the build as they are missing.

I would like the build to complete and ignore these linked files - or should there be guidance around shipping any files referenced in the documentation xml file?

Answer 1

In the Components tab of the Sandcastle Help File Builder for your project, select the 'Code Block Component' and add it to your project. When configuring it make sure 'Allow missing source code files/regions' is checked.

It is kind of misleading, as it appears that if the component is not added that it shouldn't attempt to look for these items. Note also that the Build tab 'disable the custom code block component' is different from the above so checking that will have no impact on your build error.