Getting Started with DocFX

1. What is DocFX

DocFX is an API documentation generator for .NET, which currently supports C# and VB. It generates API reference documentation from triple-slash comments in your source code. It also allows you to use Markdown files to create additional topics such as tutorials and how-tos, and to customize the generated reference documentation. DocFX builds a static HTML website from your source code and Markdown files, which can be easily hosted on any web servers (for example, github.io). Also, DocFX provides you the flexibility to customize the layout and style of your website through templates. If you are interested in creating your own website with your own styles, you can follow how to create custom template to create custom templates.

DocFX also has the following cool features:

  • Integration with your source code. You can click "View Source" on an API to navigate to the source code in GitHub (your source code must be pushed to GitHub).
  • Cross-platform support. We have an exe version that runs natively on Windows and with Mono it can also run on Linux and macOS.
  • Integration with Visual Studio. You can seamlessly use DocFX within Visual Studio.
  • Markdown extensions. We introduced DocFX Flavored Markdown(DFM) to help you write API documentation. DFM is 100% compatible with GitHub Flavored Markdown(GFM) with some useful extensions, like file inclusion, code snippet, cross reference, and yaml header. For detailed description about DFM, please refer to DFM.
Warning

Prerequisites Visual Studio 2017 is needed for docfx metadata msbuild projects. It's not required when generating metadata directly from source code (.cs, .vb) or assemblies (.dll)

2. Use DocFX as a command-line tool

Step1. DocFX ships as a chocolatey package. Install docfx through Chocolatey by calling choco install docfx -y.

DocFX also ships as a Homebrew package owned by community users, install with brew install docfx.

Alternatively, you can download and unzip docfx.zip from https://github.com/dotnet/docfx/releases, extract it to a local folder, and add it to PATH so you can run it anywhere.

Step2. Create a sample project

docfx init -q

This command generates a default project named docfx_project.

Step3. Build the website

docfx docfx_project\docfx.json --serve

Now you can view the generated website on http://localhost:8080.

3. Use DocFX integrated with Visual Studio

Step1. Create a Class Library (.NET Framework) project

Step2. Right click on the project and select Manage NuGet Package

Step3. Search and install the docfx.console NuGet package. It adds itself to the build targets and adds the docfx.json configuration file along with other files.

Step4. Build the project, and a _site folder will be generated with the documentation.

Note

Possible warning:

  • Cache is corrupted: if your project targets multiple frameworks, you have to indicate one to be the main for the documentation, through the TargetFramework property in docfx.json:

    "metadata": [ { "src": "...", "dest": "...", "properties": { "TargetFramework": <one_of_your_framework> } }, ]

4. Use DocFX with a Build Server

4.1 Steps

DocFX can be used in a Continuous Integration (CI) environment.

Consider a typical scenario: I want to set up a job on a CI service (e.g. Azure Pipelines) to build documents automatically and publish to a website (e.g. GitHub Pages). We can achieve this by a script on CI jobs with following steps:

  1. clone repo
  2. choco install docfx
  3. docfx {docsetPath}, while you can change build.dest in docfx.json to set the output path
  4. push all the content in docsetPath/_site to gh-pages branch
Note

These steps give an overall impression of what to do. You can adjust them depending on actual scenario.

docfx-seed project provides a sample integrating with AppVeyor.

4.2 Set branch name

Most build systems do not checkout the branch that is being built, but use a detached head for the specific commit. DocFX needs the branch name to implement the View Source link in the API documentation.

Many build systems set an environment variable with the branch name. DocFX uses the following automatically:

Setting the environment variable DOCFX_SOURCE_BRANCH_NAME tells DocFX which branch name to use, if the CI service you use is not in the list above.

Note

Known issue in AppVeyor: Currently platform: Any CPU in appveyor.yml causes docfx metadata failure. https://github.com/dotnet/docfx/issues/1078

5. Build from source code

As a prerequisite, you need:

Step1. git clone https://github.com/dotnet/docfx.git to get the latest code.

Step2. Run build.cmd under root folder.

Step3. Add artifacts folder to nuget source by in IDE:

Tools > NuGet Package Manager > Package Manager Settings > Package Sources

Step4. Follow steps in #2, #3, #4 to use DocFX in command-line, IDE or .NET Core.

6. A seed project to play with DocFX

Here is a seed project: https://github.com/docascode/docfx-seed. It contains

  1. A basic C# project under src.
  2. Several conceptual files under articles.
  3. An overwrite file to add extra content to API under specs.
  4. toc.yml under root folder. It renders as the navbar of the website.
  5. docfx.json under root folder. It is the configuration file that docfx depends upon.
Tip

It's good practice to separate files with different types into different folders.

7. Q&A

  1. Q: How do I quickly reference APIs from other APIs or conceptual files? A: Use @uid syntax.
  2. Q: What is uid and where do I find uid? A: Refer to Cross Reference section in DFM.
  3. Q: How do I quickly find uid in the website? A: In the generated website, hit F12 to view source, and look at the title of an API. You can find uid in data-uid attribute.