Generating Documentation With DocFX as Part of a VS Solution

I have a couple of small open-source projects out there. For me, the hardest part of getting such projects into a state which allows others to use them effectively is creating documentation - I only have enough discipline to put triple-slash-comments on the public API. In the past, I've been using Sandcastle Help File Builder to create help files based on that, but it slowly starts to feel heavy and outdated. So when Microsoft announced the move of .NET Framework docs to docs.microsoft.com with information that it is being powered by DocFX, I decided this is what I would try the next time I had to set up documentation for a project. Also, based on my previous experience, I've set some requirements:

• The documentation needs to be part of the Visual Studio solution.
• The documentation should be generated on the build.
• The documentation should be previewable from Visual Studio.

When Lib.AspNetCore.Mvc.JqGrid reached the v1.0.0 I had the opportunity to try to do this.

Dedicated Project for Documentation

I wanted to keep the documentation as part of the solution, but at the same time, I didn't want it to pollute the existing projects. Creating separated projects just for the documentation seemed like a good idea, I just needed to decide on the type of project. DocFx generates the documentation as a website so a web application project felt natural. It also helped to address the "previewable from Visual Studio" requirement. The built-in preview functionality of DocFx requires going to the command line (yes, I could try to address that with the PostcompileScript target). I've created an empty ASP.NET Core Web Application and enabled static file support.

public class Startup
{
    ...

    public void Configure(IApplicationBuilder app)
    {
        app.UseDefaultFiles()
            .UseStaticFiles();
    }
}

Setting up DocFx

The DocFx for Visual Studio is available in the form of a docfx.console package. The moment you install the package it will attempt to generate documentation when the project is being built. This means that the build will start crashing because the docfx.json file is missing. After consulting the DocFX User Manual I've come up with the following file:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "Lib.AspNetCore.Mvc.JqGrid.Infrastructure/Lib.AspNetCore.Mvc.JqGrid.Infrastructure.csproj",
            "Lib.AspNetCore.Mvc.JqGrid.Core/Lib.AspNetCore.Mvc.JqGrid.Core.csproj",
            "Lib.AspNetCore.Mvc.JqGrid.DataAnnotations/Lib.AspNetCore.Mvc.JqGrid.DataAnnotations.csproj",
            "Lib.AspNetCore.Mvc.JqGrid.Helper/Lib.AspNetCore.Mvc.JqGrid.Helper.csproj"
          ],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": ".."
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [ "api/*.yml" ]
      }
    ],
    "dest": "wwwroot"
  }
}

The metadata section tells DocFx what it should use for generating the API documentation. The src property inside the src section allows for setting the base folder for the files property, while the files property should point to the projects which will be used for generation. The dest property defines the output folder for generation processes. This is not the documentation yet. The actual documentation is being created in the second step which is configured through thebuild section. The content tells DocFx what to use for the website. Here we should point to the output of the previous step and any other documents we want to include. The dest property is where the final website will be available - as this is a context of the web application, I've targeted wwwroot.

Building the documentation project resulted in disappointment in the form of "Cache is not valid" and "No metadata is generated" errors. What's worse, the problem was not easy to diagnose as those errors were reported for a number of different issues. After spending a considerable amount of time looking for my specific issue, I stumbled upon DocFx v2.16 release notes which introduced a new TargetFramework property for handling projects which are using TargetFrameworks in the csproj. That was exactly my case. The release notes described how to handle complex scenarios (where documentation should be different depending on TargetFramework) but mine was simple, so I just needed to add the property with one of the values from csproj.

{
  "metadata": [
    {
      ...
      "properties": {
        "TargetFramework": "netstandard1.6"
      }
    }
  ],
  ...
}

This resulted in a successful build and filled up wwwroot/api with HTML files.

Adding Minimum Static Content

The documentation is not quite usable yet. It's missing a landing page and a top level Table of Contents. The Table of Contents can be handled by adding toc.yml or toc.md to the content, DocFx will render it as the top navigation bar. I've decided to go with the markdown option.

# [Introduction](index.md)

# [API Reference](/api/Lib.AspNetCore.Mvc.JqGrid.Helper.html)

As you can guess, index.md is the landing page, so it should also be added to the content.

{
  ...
  "build": {
    "content": [
      {
        "files": [
          "api/*.yml",
          "index.md",
          "toc.md"
        ]
      }
    ],
    ...
  }
}

Adjusting Metadata

The last touch is adjusting some metadata values like title, footer, favicon, logo, etc. The favicon and logo require some special handling as they contain paths to resources. In order for a resource to be accessible by DocFx, it has to be added to the dedicated resource section inside build.

{
  ...
  "build": {
    ...
    "resource": [
      {
        "files": [
          "resources/svg/logo.svg",
          "resources/ico/favicon.ico"
        ]
      }
    ],
    ...
    "globalMetadata": {
      "_appTitle": "Lib.AspNetCore.Mvc.JqGrid",
      "_appFooter": "Copyright © 2016 - 2017 Tomasz Pęczek",
      "_appLogoPath": "resources/svg/logo.svg",
      "_appFaviconPath": "resources/ico/favicon.ico",
      "_disableBreadcrumb": true,
      "_disableAffix": true,
      "_disableContribution": true
    }
  }
}

This has satisfied my initial requirements. The further static content can be added exactly the same as index.md has been added, while the look and feel can be customized with templates.