Summer Of Docs - Documenting .NET Libraries

Summer is here, the city finally feels like you can take pictures of it from above without being “head in the clouds”, and that also means that it’s time to document how we generate .NET documentation on docs.microsoft.com.

A while ago I wrote a post about documenting NuGet packages, and while it was a generally good description of high-level tools, it also missed the key detail - how to use DocFX to render the docs.

More than that, I want to show how to do that on a platform other than Windows; all instructions in this article can be followed on a Mac (and if you have some time on your hands, Linux) with the exception of YAML generation, because it’s currently blocked by a bug with the ECMA2YAML extension.

Getting and Configuring DocFX #

First thing you need to do is download and install DocFX. Once the download completes, make sure to extract it in a folder of your choice.

Next, you need to install Mono. On a Mac, you can just use Homebrew (brew install mono) or download it directly from the Mono website.

Once done, you can navigate to a folder where you want to initialize your documentation, and run:

mono --arch=32 $HOME/Downloads/docfxtest/docfx.exe init

Obviously, the path can be different, depeneding on where you downloaded DocFX. This will create the skeleton for the documentation.

Generating Compatible Documentation #

Next, we need to make sure that we get the ECMA2YAML extension. On our team, we rely on documentation for .NET assemblies that is generated with the help of mdoc - an open-source documentation generation tool that creates ECMAXML from assemblies and their Roslyn-generated XML documentation files. By default, DocFX cannot read in ECMAXML files, so we need the extension.

The easy way to operate with ECMA2YAML on is to download the extension locally (thanks NuGet.org for having that functionality), extracting it and using the /tools/ECMA2Yaml.exe binary to translate ECMAXML to DocFX-ready YAML. Refer to my previous article if you need to know how to run mdoc and generate ECMAXML docs.

You can use two parameters - -s, to specify where the XML files are coming from, and -o for the target folder where you will place the output.

When the files are generated, make sure to copy the YAML files wherever you originally triggered docfx init, in the api folder. It’s OK to replace the existing TOC.yml as it’s there just for placeholder purposes.

Once the build completes, run:

mono --arch=32 $HOME/Downloads/docfxtest/docfx.exe serve _site

This will provision a new web server running locally on port 8080:

Room for Improvement #

Of course, the process here is somewhat manual and if you are running a Windows VM, you can already automate this, similar to what we are doing on docs.microsoft.com. Once ECMA2YAML is fixed to account for *nix paths, we will be able to put this within an agent that runs across all platforms that can run mono. In some of the next installments of the Summer of Docs I will talk about how we can Docker-ize the process and make it more extensible.