1

We have an SDK project that includes a test engine. These live under two different csproj's. So we have SDK.csproj and TestEngine.csproj where SDK.csproj is a ProjectReference.

I have a DocFx project set up that builds metadata for these two separately, with docfx.json metadata that looks like this:

{
  "src": [
  {
    "src": "../../sdk",
    "files": ["csharp/SDK/**/*.cs"]
  }],
  "dest": "reference/SDK"
},
{
  "src": [
  {
    "src": "../../sdk",
    "files": ["csharp/TestEngine/**/*.cs"]
  }],
  "dest": "reference/TestEngine"
}

This way I can set up TOC's to put these documentation trees under separate tabs.

However, I cannot use a cref in TestEngine xml docs that refers to a class from SDK. I get an error like this from DocFX build: Warning:[MetadataCommand.ExtractMetadata]Invalid cref value "!:SDK.SDKClass" found in triple-slash-comments for TestEngineClass, ignored.

I can imagine why this fails - DocFX is generating the metadata for TestEngine alone so it doesn't know about the SDK classes or how to link to them. Is there a way I can change the configuration so that I can keep these two projects separate (under separate TOC's) in the final website but still link from TestEngine to SDK classes?

ryryguy
  • 610
  • 4
  • 15
  • Oh! I've found that `@` references work on the pages generated from the triple slash comments. So `@SDK.SDKClass` works in place of `` in my example. For some reason I thought this only worked on the Markdown articles. (This may be DocFx specific, and I'm curious if there is another solution, so I won't add this as an answer to this question just yet) – ryryguy May 20 '20 at 18:32

1 Answers1

1

I realized that using @ and/or xref tags as described in the DocFx documentation do resolve to links properly in the generated web pages. So that gets me a lot of what I want. However, it's not a complete solution as other generated references do not resolve to links. For example, if a TestEngine method has a parameter of type SDK.SDKClass, the generated docs won't make a link for SDKClass where it appears on the parameter documentation. So I'm still wondering if there is another solution.

ryryguy
  • 610
  • 4
  • 15