DocFX `Invalid cref value "!:Exception" found in triple-slash-comments for` on Azure Pipeline

Question

I have an issue with DocFx when running on an azure pipeline where DocFx reports Invalid cref value "!:Exception" found in triple-slash-comments for for this and many standard .net objects.

This only happens on the azure pipeline, not if I run docfx <MyProjectName>/docfx.json locally in Visual Studio developer terminal.

I am using classic pipeline and the Create DocFx Documentation task type.

The YAML equivalent is:

- task: chrismason.vsts-docfxtasks.docfx-extension-build-task.DocFxTask@0
  displayName: 'Create Top Level Documentation'
  inputs:
    solution: src/<MyProjectName>/docfx.json
    docfxOptions: /Documentation/docfx.json

I am NuGet restoring the project and building the project in the previous step, although if I remove the build step it does not make much difference to the output for the build documentation.

I have replaced the project name with <MyProjectName> for the purpose of this being a public post.

The docfx.json file looks like this, albeit with correct project names, and a little name obfuscation.

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "Project1/Project1.csproj",
            "Project2/Project2.csproj",
            "Project3/Project3.csproj"
          ],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": ".."
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "toc.yml",
          "index.md",
          "api/**.md",
          "api/**.yml",
          "api/toc.yml"
        ]
      }
    ],
    "dest": "website",
    "fileMetadataFiles": [],
    "globalMetadata": {
      "_appTitle": "???? Core Library",
      "_appName": "???? Core Library",
      "_appFooter": "Copyright ????",
      "_appFaviconPath": "resources/ico/favicon.ico",
      "_appLogoPath": "resources/png/logo.png",
      "_disableNavbar": false,
      "_disableBreadcrumb": false,
      "_disableToc": false,
      "_disableContribution": true,
      "_enableSearch": true,
      "pdf": false,
      "generatesAppendices": "true"
    },
    "globalMetadataFiles": [],
    "resource": [
      "Resources/ico/favicon.ico",
      "Resources/png/logo.png",
    ],
    "template": [
      "default",
      "modern"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

The projects are all .NetCore 8.0

Answer 1

I can reproduce the issue. In my test, "Invalid cref value ..." in the pipeline is just a warning instead of an error, and it does not affect the successful run of the task.

The warnings are related to the version of docfx. When using "Create DocFx Documentation" task, it will download docfx with version 2.59.4 by default.

To resolve the warning, you can download the latest version docfx 2.77.0 in a command line and run docfx directly, instead of using "Create DocFx Documentation" task. For example,

- powershell: |
    dotnet tool update -g docfx
    docfx docfx_project/docfx.json
    if ($lastexitcode -ne 0){
      throw ("Error generating document")
    }
  displayName: "Documentation"