Docfx helps us make documentation easier for .NET
One of the most tedious jobs of being a developer is maintaining documentation, but it shouldn’t be a difficult task. When writing documentation, one doesn’t always want to be concerned about how things look per se, but rather how things are communicated. Having to focus on just writing and not "the other stuff" is very important.
Currently supporting languages C# and VB.NET, Docfx is an API documentation generator for .NET. If you have worked with JSDoc or Sphinx before, you will notice that Docfx is a similar concept. It doesn’t just have the ability to directly read the triple-slash comments in code, but also includes a syntax for deep linking to objects and additional files with extra information. These files are written in a special Markdown format called Docfx Flavored Markdown (DFM) which is completely compatible with GitHub’s Markdown.
The documentation generation is based on a pre-defined template supporting the Mustache syntax and is completely customizable.
Using Docfx
At the time of writing this article, one can either use the executable directly, from within Visual Studio 2015 or as a command on DNX (.Net Execution Environment).
Use it directly
The quickest way to get started is to get your hands dirty and play around with this awesome tool. After downloading the latest release on GitHub, navigate to your target documentation folder using Command Prompt and initialize a default project:
docfx.exe init -q
This will initiate a configuration file called docfx.json inside the target directory.
Note that I have included a sample C# project under the /src directory that contains a bunch of sample code and xml comments.
The next step is to actually generate and serve up the documentation using the given configuration:
docfx.exe docfx.json --serve
This will generate and serve up a compiled copy of the documentation as a static HTML site on http://localhost:8080.
You can now also combine it with additional content. Here’s an example of a Hello.md file I’ve added to the root directory:
To have this page show up in the navigation and be part of the rest of the documentation, we need to also add a toc.yml file containing all the links:
After running the build & serve command we now get this result:
Using Docfx from within Visual Studio
You can include a documentation build task to run every time you build a project in Visual Studio. Simply add the Docfx.msbuild Nuget package:
Install-Package docfx.msbuild
This will add the necessary toc.yml and docfx.json files to the project for your configuration and the documentation site will be generated inside the /_site folder every time you build the project.
Using Docfx under the .NET Execution Environment (DNX)
To run Docfx as a command for DNX, as a prerequisite; the latest version of the .NET Version Manager (DNVM) and the .NET Utilities (DNU) must be installed. Reference the documentation of ASP.NET Core for more information.
After installing all the prerequisites, we need to make sure to target the right source for installing Docfx as it depends on the latest release version of ASP.NET Core 1.0.0-rc1, by setting the DNX_FEED environment variable. Thereafter we install the Docfx command for ASP.NET Core.
SET DNX_FEED=https://www.myget.org/F/aspnetrelease/api/v2/
dnu commands install docfx
Now that Docfx is a command, we could simply use it to build the documentation site by either executing docfx build (or just docfx) and then serving it up on a local server:
docfx build
docfx serve
In closing
Now that we’ve seen how easy it is to create, generate and maintain documentation for the .NET platform using Docfx, I urge you to go to https://dotnet.github.io/docfx to learn more and start playing around with this great tool. Who knows, it might find itself in your next project!