Figure out how to publish XML documentation on our website

[rolfbjarne]

Ref: #14372, step 2.

This task partially depends on #17395.

Note: Microsoft tends to call API docs API ref, or reference docs. Some of the links here will use those terms.

The process for publishing API docs can be found here:

• .NET reference requirements - Repo admin guide | Microsoft Learn
• .NET API Documentation | Microsoft Learn.

A high-level overview is:

1. Drop binaries (assemblies + compiler generated XML files) into an internal binaries repo.
2. Trigger a CI job in OPS. This runs a tool chain that generates the ECMA-XML and checks it into a GitHub repo.
3. Docs build runs on GitHub repo and converts the ECMA-XML to web pages, which are published to an internal review site.
4. Merge PR on GitHub to main and live and the API docs get published.

It’s a process that initially, getting everything to build, will most likely be quite painful. But once the initial hurdles are overcome it should tick along without any problems. For MAUI it was a 2-3 month process (in elapsed time) to go from first dropping binaries into the repo to having published API docs.

Binaries repo

This is the binaries repo: https://apidrop.visualstudio.com/_git/binaries.

The idea is you have a top-level folder for your repo:

The folder name needs to match the ms.prod value for the product [1]. Within the folder you have a folder for each release of your docs. These folder names correspond to something called monikers [1]. Versioning is supported, so for .NET MAUI we have API docs published for .NET 6 and 7, and you can switch between the version on the docs site. There’s an expectation for .NET that you will do versioned docs (rather than the Xamarin approach of docs reflecting the latest release).

Note: we might want to use the OS version as the version pivot point instead of the .NET version, so we'd have something like:

• net-ios-15.4
• net-ios-16.0
• net-tvos-15.4
• etc..

Since our API isn't fixed within a .NET version (we shipped new API for iOS 16.0 to .NET 6 after the initial release for .NET 6 for instance).

Inside the folders for each release are the assemblies/XML files:

The dependencies folder contains any additional assemblies required to make the build succeed (e.g. if an assembly has a method that returns something from Newtonsoft.Json, the Newtonsoft.Json assembly will have to go into the dependencies folder).

Note: you can generate empty API docs (that list all the types/fields/properties etc.) just by dropping assemblies into the repo. That’s really a good first step to ensure that mdoc will succeed (it probably won’t until you get the right dependencies in the dependencies folder).

OPS

OPS (open publishing system) is the docs build system: https://ops.microsoft.com/

You may/may not have access depending on your previous interaction with docs [1].

Inside OPS a CI job that you’ll trigger to build the ECMA-XML from the binaries [1]. This runs an AzDO pipeline that runs mdoc and ECMA2YAML on the binaries. You’ll also need access to the AzDO pipeline [1]. Provided that the build succeeds, the ECMA-XML is uploaded to a branch on your GitHub API docs repo (exact branch specified by the CI job).

As you’ll probably know, mdoc exits once it finds an error and so the build process fails. This was really painful for MAUI because they’d produced all their /// before they even tried to publish API docs. So it was a case of fix one line of ///, run the CI job again, then wait for the result. Rinse and repeat, over and over again. Rather than wait 15 mins for the CI to run, they ended up installing mdoc locally to speed up the error fixing process.

GitHub repo

When any content is checked into a docs-based GitHub repo, the docs build process runs. Provided that it succeeds, you’ll then be able to review the docs on review.learn.microsoft.com.

Even when mdoc succeeds, there’ll most likely be docs build issues initially. It’s another source of pain. But at least the docs build (docfx) gives you all the build issues in one go.

Publish

Once docs are ready to publish you PR the branch into main. main then needs merging to live to publish the docs. The repo can be setup to auto-merge main to live (which is what most docs repos do) [1].

---

[1] @davidbritch can help with this.

[rolfbjarne]

The folder name needs to match the ms.prod value for the product [1].

I might be totally wrong here, but I think we need a different ms.prod value for each platform (iOS, tvOS, macOS, Mac Catalyst), because while a lot of the API is identical between the platforms, the APIs might be different in unusual/incompatible ways across platforms as well (say two platforms have the same type with the same property, but that property has a different property type between iOS and macOS):

• dotnet-ios
• dotnet-tvos
• dotnet-macos
• dotnet-maccatalyst

It seems that this can be done with a single api docs repository, is that correct?

Note: we might want to use the OS version as the version pivot point instead of the .NET version, so we'd have something like:

• net-ios-15.4
• net-ios-16.0
• net-tvos-15.4
• etc..

There's a slight wrinkle here too: we're publishing the iOS X.Y bindings for both .NET Z and .NET Z+1, and there's no technical reason those might be different (the .NET Z+1 version might have more APIs for instance - it should never have fewer/incompatible APIs though).

So if we were to be strictly correct, we'd have to pivot on both .NET version + OS version:

• net-ios-18.0-8.0
• net-tvos-18.0-8.0
• net-maccatalyst-18.0-8.0
• net-macos-15.0-8.0
• net-ios-18.0-9.0
• net-tvos-18.0-9.0
• net-maccatalyst-18.0-9.0
• net-macos-15.0-9.0

[davidbritch]

These should be ms.subservice now:

• dotnet-ios
• dotnet-tvos
• dotnet-macos
• dotnet-maccatalyst

Then we'll use monikers to control the versioning (net-ios-18.0-8.0 etc.).

It seems that this can be done with a single api docs repository, is that correct?

Correct.