Skip to content

Latest commit

 

History

History
84 lines (52 loc) · 5.18 KB

msbuild-integration.md

File metadata and controls

84 lines (52 loc) · 5.18 KB
Raw

MdDocs MSBuild Integration

Applies to: Version 0.6 and later

Installation

MdDocs is a distributed as NuGet packages.

  • Prerelease builds are available on MyGet
  • Release versions are available on NuGet.org

MdDocs can be used either as .NET CLI tool (see MdDocs .NET CLI tool) or integrated into the project build as a set of MSBuild targets.

NuGet

The package Grynwald.MdDocs.MSBuild allows generating documentation as part of the build process.

To install the package, run

dotnet add package Grynwald.MdDocs.MSBuild

or install it through the Visual Studio NuGet Package Manager

Prerequisites

The Grynwald.MdDocs.MSBuild package works in both the .NET Framework version of MSBuild included with Visual Studio and the version of MSBuild that ships with the .NET SDK. However, in both cases the MdDocs CLI is started as a child-process of the build which requires the .NET 6 (or later) runtime to be installed.

Usage

When the MSBuild package is installed, documentation can be generated by running the appropriate MSBuild targets. Optionally, the targets can be configured to automatically generate documentation when the project is built.

API Reference

To generate API reference for a project, run

dotnet msbuild <PROJECT> /t:GenerateApiReferenceDocumentation

The behaviour of the target can be customized by setting the following MSBuild properties:

Property Name Default Value Description
GenerateApiReferenceDocumentationOnBuild false Set the to true to automatically generate API documentation when the project is built.
MdDocsConfigurationFilePath mddocs.settings.json 1 Specifies the path of the configuration file to use. See Configuration for details .
ApiReferenceDocumentationOutputPath - The directory to save the generated documentation to. Overwrites the Output Path setting

1) When MdDocsConfigurationFilePath is not set, the MSBuild targets look for a file named mddocs.settings.json in the project directory or any parent directory of the project.

⚠️ Note: If the output directory already exists, all files in the output directory will be deleted.

Command Line Help

To generate command line documentation for a project, run

dotnet msbuild <PROJECT> /t:GenerateCommandLineDocumentation

The behaviour of the target can be customized by setting the following MSBuild properties:

Property Name Default Value Description
GenerateCommandLineDocumentationOnBuild false Set to true to automatically generate command line documentation when the project is built.
MdDocsConfigurationFilePath mddocs.settings.json 1 Specifies the path of the configuration file to use. See Configuration for details .
CommandLineDocumentationOutputPath - The directory to save the generated documentation to. Overwrites the Output Path setting

1) When MdDocsConfigurationFilePath is not set, the MSBuild targets look for a file named mddocs.settings.json in the project directory or any parent directory of the project.

⚠️ Note: If the output directory already exists, all files in the output directory will be deleted.

For an example of what the output looks like, have a look at the demo project.

See Also