Grynwald.XmlDocs.MarkdownRenderer 1.0.7

dotnet add package Grynwald.XmlDocs.MarkdownRenderer --version 1.0.7
NuGet\Install-Package Grynwald.XmlDocs.MarkdownRenderer -Version 1.0.7
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Grynwald.XmlDocs.MarkdownRenderer" Version="1.0.7" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Grynwald.XmlDocs.MarkdownRenderer --version 1.0.7
#r "nuget: Grynwald.XmlDocs.MarkdownRenderer, 1.0.7"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Grynwald.XmlDocs.MarkdownRenderer as a Cake Addin
#addin nuget:?package=Grynwald.XmlDocs.MarkdownRenderer&version=1.0.7

// Install Grynwald.XmlDocs.MarkdownRenderer as a Cake Tool
#tool nuget:?package=Grynwald.XmlDocs.MarkdownRenderer&version=1.0.7

Grynwald.XmlDocs.MarkdownRenderer

A library to convert C# XML Documentation Comments to Markdown based on Markdown Generator

Table of Contents

Overview

C# source code can have structured comments to provide inline API documentation. These comments are saved by the compiler as an XML documentation file.

While the Grynwald.XmlDocs package provides a library for parsing these comments into a .NET object model, this package adds the option to convert the XML documentation comments including the formatting tags to Markdown.


⚠️ Note: This library is not a complete documentation generator but is intended to serve as the basis of such a generator. The XML documentation file does not contain all members of an assembly but only the members for which the compiler found any XML documentation comments. To generate the full documentation of an assembly requires building a semantic model of that assembly which can be achieved using libraries like Mono.Cecil or Roslyn (Microsoft.CodeAnalyis).

The library will also not be able to resolve references to code element (like <see cref="SomeClass"/>). However, the conversion to Markdown can be customized.


Usage

To convert the contents of a XML documentation file, first reference the Grynwald.XmlDocs.MarkdownRenderer package in your project.

Load the documetnation file using the DocumentationFile class and then convert the documentation comments to a Markdown block using the MarkdownConverter class (MarkdownConverter is based on the Markdown Generator library):

using Grynwald.MarkdownGenerator;
using Grynwald.XmlDocs;
using Grynwald.XmlDocs.MarkdownRenderer;

// Load XML documentation file
var documentationFile = DocumentationFile.FromFile("./MyAssembly.xml");

// Convert the documentation file to a Markdown block
var converter = new MarkdownConverter();
var rootBlock = converter.ConvertToBlock(documentationFile);

// Create a Markdown document and save it to disk
var markdownDocument = new MdDocument(converter.ConvertToBlock(documentationFile));
markdownDocument.Save("./Documentation.md");

MarkdownConverter can either convert the entire documentation file or only indiviudal members or text blocks:

using Grynwald.MarkdownGenerator;
using Grynwald.XmlDocs;
using Grynwald.XmlDocs.MarkdownRenderer;

// Load XML documentation file
var documentationFile = DocumentationFile.FromFile("./MyAssembly.xml");

// Get a single text block from the documentation file
// (e.g. the summary of the first entry)
var summary = documentationFile.Members.First().Summary;

// Convert the summary to a Markdown block
var converter = new MarkdownConverter();
var rootBlock = converter.ConvertToBlock(summary);

// Create a Markdown document and save it to disk
var markdownDocument = new MdDocument(converter.ConvertToBlock(documentationFile));
markdownDocument.Save("./summary.md");

Customizing the Markdown Output

Conversion to Markdown uses the Visitor pattern to traverse the structure of the documentation file.

To customize the Markdown output, you can create a customized visitor and then adapt MarkdownConverter to use the custom visitor:

// Create a custom visitor derived from ConvertToBlockVisitor (the default implementation)
// And override the Visit() method for the element you want to customized the output for
class CustomVisitor : ConvertToBlockVisitor
{
    public CustomVisitor(IMarkdownConverter markdownConverter) : base(markdownConverter)
    { }

    public override void Visit(ExceptionElement exception)
    {
        // TODO: Add customized logic, e.g. to resolve the reference to an exception type
        base.Visit(exception);
    }
}

// Create a custom converter derived from MarkdownConverter (the default implementation)
class CustomConverter : MarkdownConverter
{
    // Override the CreateConvertToBlockVisitor() method to use the custom visitor defined above
    protected override ConvertToBlockVisitor CreateConvertToBlockVisitor()
    {
        return new CustomVisitor(this);
    }
}

License

Grynwald.XmlDocs.MarkdownRenderer is licensed under the MIT License.

For details see https://github.com/ap0llo/xmldocs/blob/master/LICENSE

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.7 281 12/13/2022
1.0.6 261 12/12/2022