Getting started with DocFx

I have been lately pretty impressed with the DocFx, Microsoft’s static documentation generator. In this blog post, I thought I would outline how easy it is to configure the DocFx for generating documentation for your project.

Assumption : Project already has Xml documentations enabled and the code have the necessary comments.

Step 1 : Install Chocolatey

• Head over to Chocolatey’s official website and copy the command given in the getting started page.
• Open the Powershell with Administrative prileges and executed the command copied.

For reference, the command is as follows.

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Step 2 : Install Docfx

• Install Doxfx with following command

cinst docfx -y

Step 3 : Generate DocFx Project

• Generate Sample DocFx Project for your Project Documentation with the following command.

docfx init -q

Or if you would like to dictate the name for your project.

docfx init -q -o <DocumentationProjectName>

This would generate sample project for your purpose.

Step 4: Specify Project Details

The next step is to specify the location of your Project Files. This has to be mentioned in the docfx.json file.

I am including only the relavant part of docfx.json.

"src": [
        {
          "files": "src/infrastructure/Nt.Infrastructure.UI/**.csproj",
          "cwd": "..",
          "src": "../.."
        }

As you can observe, we have used base path using the src and cwd values, and use the files to specify the projects under consideration.

Step 5 : Build and Generate your documentation website.

That’s all the configuration you would need. Rest of the magic would be done by Docfx for you. To build the project and generate the website, you need to use the following command.

docfx --serve

And there you have it, you have your documentation up and running in the development server. You could access it via (http://localhost:8080/).

We will explore more features of DocFx and related configuration in later post, but surely, this would get you started.