RefDocGen - Reference Documentation Generator for .NET

RefDocGen is a reference documentation generator for .NET.

💡 The README covers everything you’ll need for most scenarios. For the complete reference, please visit the documentation on GitHub Pages.

Features

• easy to use (installed as a .NET tool)
• supports all standard XML documentation tags
• resolves inheritdoc tags
• modern, responsive UI supporting both light and dark mode
• support for documentation versioning
• option to add custom pages (index, FAQ, ...)
• built-in search functionality

Default UI:

Demos

• reference documentation of an example library
• reference documentation of this project
• reference documentation of Newtonsoft.JSON
• reference documentation of YamlDotNet
• reference documentation of Serilog

Installation

Prerequisites:

• .NET 8 (or higher)

Install as a .NET global tool from NuGet:

dotnet tool install --global RefDocGen

This makes the refdocgen command available on the command line.

Usage

Prerequisites

Before generating documentation, it is necessary to build the project/solution in Debug configuration. The following MSBuild properties must be set:

• GenerateDocumentationFile=true - creates the XML file with documentation
• CopyLocalLockFileAssemblies=true - ensures all dependencies are copied to the output folder

Ideally, specify these properties on the command line, as follows:

dotnet build -p:GenerateDocumentationFile=true -p:CopyLocalLockFileAssemblies=true

It is also possible to set them in the project file or in the Directory.Build.props.

Important: RefDocGen doesn't support .NET Framework projects.

Running

Run the following command to generate reference documentation:

refdocgen INPUT [OPTIONS]

The only mandatory argument is the INPUT - an assembly/project/solution to document, or a YAML configuration file (further explained below).

Examples

refdocgen MyLibrary.dll
refdocgen MyLibrary.csproj
refdocgen MyLibrary.sln

Configuration

All available options are listed below (the same output can be displayed by running refdocgen --help):

INPUT (pos. 0)                                  Required. The assembly, project, or solution to
                                                document, or a YAML configuration file.

-o DIR, --output-dir=DIR                        (Default: reference-docs) The output directory
                                                for the generated documentation.

-t TEMPLATE, --template=TEMPLATE                (Default: Default) The template to use for the
                                                documentation. Valid values: Default

-v, --verbose                                   (Default: false) Enable verbose output.

-f, --force-create                              (Default: false) Forces the creation of the
                                                documentation. If the output directory already
                                                exists, it will be deleted first.

-s, --save-config                               (Default: false) Save the current configuration
                                                to a YAML file.

--static-pages-dir=DIR                          Directory containing additional static pages to
                                                include in the documentation.

--doc-version=VERSION                           Generate a specific version of the documentation.

--min-visibility=VISIBILITY                     (Default: Public) Minimum visibility level of
                                                types and members to include in the
                                                documentation. Valid values: Private,
                                                FamilyAndAssembly, Assembly, Family,
                                                FamilyOrAssembly, Public

--inherit-members=MODE                          (Default: NonObject) Specify which inherited
                                                members to include in the documentation. Valid
                                                values: None, All, NonObject

--exclude-projects=PROJECT [PROJECT...]         Projects to exclude from the documentation.

--exclude-namespaces=NAMESPACE [NAMESPACE...]   Namespaces to exclude from the documentation.

--help                                          Display this help screen.

--version                                       Display version information.

Adding custom static pages

You can include static pages (like index or FAQ) in the generated documentation, following the steps below:

• create a directory (e.g., static-pages/) with .md (preferred) or .html files
• each file represents a page and should contain its the body content
• run the generator with:

--static-pages-dir static-pages/

• thus, the pages are included in the documentation, and links to them appear in the top menu

Important: The static pages are not designed to offer the functionality of a full-fledged SSG. If you want more control over the pages, is advised to use an SSG, such as Jekyll, for user documentation.

Additional notes:

• It is possible to use relative links between pages. (Links to .md files are automatically updated to point to the correct output HTML files in the generated documentation.)
• you can include images, JS, or any other resources in the static pages directory, and then reference them from the pages
• it is possible to put the pages (and other files) into subdirectories of the static-pages/ directory (however, pages nested three or more levels deep will not appear in the top menu)
• in case you use HTML pages, to add custom CSS styles, put them into /css/styles.css and they will be included automatically (however, use custom styles only for minor tweaks, rather than completely changing the overall appearance of the page)

Example

Example directory structure:

static-pages/
    index.md
    FAQ.html

index.md

# MyLibrary Reference Documentation

This page contains the reference documentation for MyLibrary.

## Installation
To install, run `dotnet tool install my-library`.

FAQ.html

<h1>FAQ</h1>

<h6>Q1: How to install the library?</h6>
<div class="fw-light">A1: ...</div>

FAQ.md

# FAQ

## Q1: How to install the library?
## A1: ...

Documentation versioning

You can optionally generate versioned documentation, which allows users to switch between multiple versions. To do this, use the --doc-version option.

The version can then be switched using the dropdown menu at the bottom of the page.

Examples

Generate two versions of the documentation using these commands (the output directory must be the same):

refdocgen MyLibrary.dll --doc-version v1.0

# after version 1.1 is published
refdocgen MyLibrary.dll --doc-version v1.1

The documentation versions do not necessarily have to match the library versions. For example, you may create two documentation versions: one showing only the public API, and another including private members, as illustrated below:

refdocgen MyLibrary.dll --doc-version v1.0-public
refdocgen MyLibrary.dll --doc-version v1.0-private --min-visibility Private

An example of versioned documentation can be found here.

YAML configuration

You can use a YAML file to configure RefDocGen instead of specifying options on the command line. This approach makes it easy to reuse and share your configuration.

The YAML file can be generated automatically using the --save-config flag (preferred) or created manually. It is recommended to name the file refdocgen.yaml.

YAML configuration closely mirrors the command-line options:

• Each YAML key matches its corresponding command-line option (without leading dashes). For example, the output-dir key in YAML corresponds to the --output-dir option.
• The only required key is input, just as on the command line.
• The save-config option is not supported in YAML, as it doesn't make sense here
• Default values are the same as those used for command-line options.

Example

The following command generates a YAML configuration file as shown below:

refdocgen MyLibrary.sln 
    -o custom-folder
    --verbose 
    --force-create 
    --min-visibility Private 
    --exclude-projects MyLibrary.Tests 
    --exclude-namespaces MyLibrary.Internal MyLibrary.Experimental 
    --save-config # save the configuration into YAML

refdocgen.yaml

input: MyLibrary.sln
output-dir: custom-folder
template: Default
verbose: true
force-create: true
min-visibility: Private
inherit-members: NonObject
exclude-projects:
  - MyLibrary.Tests
exclude-namespaces:
  - MyLibrary.Internal
  - MyLibrary.Experimental

The next time we want to use the same configuration, we just need to run refdocgen refdocgen.yaml and the configuration will be loaded from the YAML.

Templates

Currently, only the Default documentation template is available. However, it is possible to create custom templates, as described in the official documentation.

Limitations

Default UI languages

While RefDocGen supports programs written in any .NET language, the default UI displays type and member signatures only in C# syntax. However, the default UI is designed to be extensible, so adding support for other languages, such as F#, is possible in the future.

Supported modifiers

RefDocGen recognizes most of the C# modifiers and displays them. However, some modifiers are not supported and therefore do not appear in the generated documentation.
These are typically implementation details that do not affect the public API.

More specifically, the following modifiers are not supported: extern, file, managed, new, partial, record, scoped, unmanaged, unsafe, volatile.

Additionally, these type parameter constraints are not supported: notnull, unmanaged, default, allows ref struct.

Non-nullable reference types

Currently, RefDocGen doesn't differentiate between nullable non-nullable reference types.