[Bug] `docfx metadata` does not generate all metadata on Ubuntu

[AristurtleDev]

Describe the bug
We are using DocFX to generate markdown API documentation based on two projects. The generation is run through a GitHub Action running on ubuntu-latest. It's been discovered that when running on Ubuntu, the dotnet docfx metadata command will skip all except the last glob listed in the metadata.src.files array.

For example, here is the docfx.json configuration file.

{
    "metadata": [
      {
        "outputFormat": "markdown",
        "src": [
          {
            "src": ".",
            "files": [
              "external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj",
              "external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj"
            ]
          }
        ],
        "dest": "./content/api",
        "includePrivateMembers": false,
        "disableGitFeatures": false,
        "disableDefaultFilter": false,
        "noRestore": false,
        "namespaceLayout": "flattened",
        "memberLayout": "samePage",
        "EnumSortOrder": "alphabetic"
      }
    ]
}

With this configuration file, when run on windows-latest and macOS-latest GitHub runners, the following is output

dotnet docfx metadata
Using .NET Core SDK 8.0.100
Loading project /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj
  Determining projects to restore...
  Restored /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj (in 1.08 sec).
Loading project /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj
  Determining projects to restore...
  Restored /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj (in 443 ms).
  1 of 2 projects are up-to-date for restore.

...

Export succeed: 460 items

However on ubunutu-latest the following is output

dotnet docfx metadata
Using .NET Core SDK 8.0.100
Loading project /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj
  Determining projects to restore...
  Restored /Users/aristurtle/Desktop/monogame-11ty/external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj (in 443 ms).
  1 of 2 projects are up-to-date for restore.

...
Export succeed: 275 items

As you can see it skips the first file listed in the metadata.src.files array and only runs the last file listed.

Note:
If the configuration is updated so that it only contains the MonoGame.Framework.DesktopGL.csproj in the metadata.src.files array, then it will generate the metadata for that project correctly on the ubuntu-latest runner. However, if both csproj files are listed, no matter the order they are listed, it only executes the MonoGame.Framework.Content.Pipeline.csproj

To Reproduce
A minimal example repository has been created at https://github.com/AristurtleDev/docfx-ubuntu-issue

The following steps should be performed in a windows, mac, and ubuntu environment to see the difference in how it runs in ubuntu vs mac/windows.

Steps to reproduce the behavior:

1. Clone the minimal example repository git clone https://github.com/AristurtleDev/docfx-ubuntu-issue.git
2. cd into directory
3. Restore dotnet tools dotnet tool restore
4. Run the DocFX metadata command dotnet docfx metadata

Expected behavior
Metadata documentation is generated for both csproj files listed in the metadata.src.files array in docfx.json.

Actual behavior
Metadata documentation is only generated for one csproj when running on the ubuntu-latest GitHub runner.

Context (please complete the following information):

• OS: Windows, Mac, Ubuntu
• Docfx version: [e.g. 2.74.1]

Additional context
You can view the output of the minimal sample repo for each operating system at the following links

• Windows: https://github.com/AristurtleDev/docfx-ubuntu-issue/actions/runs/7552372225/job/20561129343
• MacOS: https://github.com/AristurtleDev/docfx-ubuntu-issue/actions/runs/7552372222/job/20561129355
• Ubuntu: https://github.com/AristurtleDev/docfx-ubuntu-issue/actions/runs/7552372224/job/20561129340

This is also in reference to the following issue MonoGame/monogame.github.io#58

[filzrev]

On Windows / macOS environment.
Projects are analyzed with following orders.

1. MonoGame.Framework.DesktopGL.csproj
2. MonoGame.Framework.Content.Pipeline.csproj

On Ubuntu environment.
This processing is done in reverse order.

If explicitly reversing processing order with projectFiles.Reverse().
It can reproduce this problem on Windows environment.

docfx/src/Docfx.Dotnet/DotnetApiCatalog.Compile.cs

Lines 68 to 77 in d79836f

	if (files.TryGetValue(FileType.Project, out var projectFiles))
	{
	foreach (var projectFile in projectFiles)
	{
	if (await LoadCompilationFromProject(projectFile.NormalizedPath) is { } compilation)
	{
	projectCompilations.Add(compilation);
	}
	}
	}

---

This problems occurs when using markdown output option.
It works as expected, when using mref output options.

[AristurtleDev]

Thanks for finding this @filzrev.
In our particular setup, we explicitly need to use the markdown option and not mref since we use 11ty as the overall static site generator and DocFx just for the .NET Api documentation generation.

Curious though why reversing the order would cause it to skip processing the second glob and why it reversed on Ubuntu

[filzrev]

There is following output message difference. (Tested on Windows environment)

• Default Order: Export succeed: 460 items
• Reverse Order: Export succeed: 275 items

It seems missing markdown files have following namespaces.

• Microsoft.Xna.Framework
• Microsoft.Xna.Framework.Content
• Microsoft.Xna.Framework.Graphics
• MonoGame.Framework.Utilities

And other namespace files (e.g. Microsoft.Xna.Framework.Input) seems correctly outputted.

---

When adding empty namespace definition (namespace Microsoft.Xna.Framework.Input.Dummy { }) at MonoGame.Framework.Content.Pipeline project.
Then Microsoft.Xna.Framework.Input namespace files are not outputted as expected.

So reproduction conditions are thought to be

1. Using markdown output option.
2. Define same namespaces in multiple projects.

I can't able to identifying the root cause of the problem, but we hope it helped to resolve docfx problems.