How to generate documentation with DocFX using XML documentation file?

Question

I want to create something like API documentation website for a .NET project. As per .NET Docs the XML comments that we put on top of methods, classes etc. can be processed into an XML file by the compiler and that file can be run through tools like DocFX to generate the documentation website. .NET Docs does not provide any instructions for the latter and DocFX documentation also does not give any hint on how to use that XML file to create API documentation website.

Any ideas on how can I use that XML file with DocFX to generate API Documentation Website?

Have you looked at Sandcastle: https://github.com/EWSoftware/SHFB — Flydog57, Dec 29 '18 at 00:06
@Flydog57 No, not yet. I started looking into DocFX and have spent some time playing around with it but did not get to where I wanted so I thought I might as well get this one working instead of jumping around to another tool. — Baljeet Singh, Dec 29 '18 at 00:40
I've never used Sandcastle, but, as I understand it, it's made for taking XML comments and building API docs. — Flydog57, Dec 29 '18 at 00:52

score 5 · Answer 1 · answered Aug 12 '19 at 22:49

If you are using .NET Core 2.2 or greater, you can update your docfx.json to directly extract metadata from .dll and .xml.

DocFX "will lookup for the XML file in the same folder" with the same file name as .dll.

Example:

{
  "metadata": [
    {
      "src": "bin/Release/netstandard2.0/YourCompany.YourNamespace.dll",
      "dest": "obj/api"
    }
  ]
}

You should also include <GenerateDocumentationFile>true</GenerateDocumentationFile> into your .csproj file.

score 2 · Answer 2 · answered Apr 25 '19 at 08:28

For anyone stumbling across this, DocFX can be used from Visual Studio 2017 and later directly:

Install the docfx.console NuGet package to the project containing the XML documentation.
Upon building the project a _site folder will be generated in the same folder where the project's .csproj file resides. That folder contains the documentation (access via the index.html file).

Source: DocFX Documentation

How to generate documentation with DocFX using XML documentation file?

2 Answers2