MdDocs

Overview

Package	NuGet.org	MyGet
Grynwald.MdDocs
Grynwald.MdDocs.MSBuild

MdDocs is a tool to generate documentation in the form of Markdown documents. It currently supports:

• Generating API reference from a .NET assembly and the corresponding XML documentation file
• Generating command line help for projects that use the CommandLineParser package for parsing

For an example of what the output looks like, have a look at the demoprojects directory.

Documentation

For documentation on installation and usage, please refer to the corresponding sub-pages:

• MdDocs .NET CLI Tool
• MdDocs MSBuild Integration
• Configuration

Building from source

ℹ This repository uses git submodules. Use git clone --recursive to check out submodules as well.

MdDocs is a .NET Core application and can be built using the .NET SDK 3.1 (see global.json)

dotnet restore .\src\MdDocs.sln

dotnet build .\src\MdDocs.sln

dotnet pack .\src\MdDocs.sln

To run tests, the .NET SK 2.1 (version 2.1.800) and a installation of Visual Studio 2019 is requried as well. (this only applies to the MdDocs.MSBuild.IntegrationTest project, all other test project should be executable with only the .NET Core 3.1 SDK).

dotnet test .\src\MdDocs.sln

Issues

If you run into any issues or if you are missing a feature, feel free to open an issue.

I'm also using issues as a backlog of things that come into my mind or things I plan to implement, so don't be surprised if many issues were created by me without anyone else being involved in the discussion.

Acknowledgments

MdDocs was made possible through a number of libraries (aside from .NET Core and .NET Standard). Thanks to all the people contribution to these projects:

• Parts of this program are based on code from the NuDoq project, licensed under the Apache License 2.0. See XmlDocsReader.cs for details
• Mono.Cecil
• CommandLineParser
• Nerdbank.GitVersioning
• Microsoft.Extensions.Logging
• Microsoft.Extensions.Configuration
• Microsoft.DotNet.Analyzers.Compatibility
• xUnit
• Xunit.Combinatorial
• Moq
• ApprovalTests
• Microsoft.CodeAnalysis.CSharp
• Coverlet
• MSBuild
• SourceLink
• NuGet
• Newtonsoft.Json

Versioning and Branching

The version of the library is automatically derived from git and the information in version.json using Nerdbank.GitVersioning:

• The master branch always contains the latest version. Packages produced from master are always marked as pre-release versions (using the -pre suffix).
• Stable versions are built from release branches. Build from release branches will have no -pre suffix
• Builds from any other branch will have both the -pre prerelease tag and the git commit hash included in the version string

To create a new release branch use the nbgv tool (at least version 3.0.4-beta):

dotnet tool install --global nbgv --version 3.0.4-beta
nbgv prepare-release