Tomasz Pęczek

Yet Another Developer Blog

Generating documentation with DocFX as part of VS solution

.net, api-documentation, docfx, documentation-generator 0 comments

I have a couple of small open source projects out there. For me the hardest part of getting such project into state which allows others to use it 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 outdate. So when Microsoft announced the move of .NET Framework docs to docs.microsoft.com with information that it is being powered by DocFX I've decided this is what I want to try next time I will have to set up a 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 build.
  • The documentation should be previewable from Visual Studio.

When Lib.AspNetCore.Mvc.JqGrid reached the v1.0.0 I've got the opportunity to try to achieve 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 project just for the documentation seemed like a good idea, I just needed to decide on the type of project. DocFx generates the documentation as website so 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 command line (yes I could try to address that with PostcompileScript target), with web application project all I need is F5 key. I've created an empty ASP.NET Core Web Application and enabled static files support.

public class Startup
{
    ...

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

Setting up DocFx

The DocFx for Visual Studio is available in form of docfx.console package. The moment you install the package it will attempt to generate documentation when project is being build. This means that the build will start crashing because the docfx.json file is missing. After consulting the Doc​FX User Manual I've came up with 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 src section allows for setting the base folder for 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 process. This is not the documentation yet. The actual documentation is being created in the second step which is configured through build 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 web application I've targeted wwwroot.

Building the documentation project resulted in disappointment in form of "Cache is not valid" and "No metadata is generated" errors. What's worst the problem was not easy to diagnose as those errors are being reported for a number of different issues. After spending considerable amount of time looking for my specific issue I've stumbled upon DocFx v2.16 release notes which introduced 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 values from csproj.

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

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

Adding minimum static content

The documentation is not quite usable yet. It's missing landing page and 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 markdown option.

# [Introduction](index.md)

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

As you can guess index.md is the landing page, 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 resource to be accessible by DocFx it has to be added to 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 look and feel can be customized with templates.