Grynwald.XmlDocs.MarkdownRenderer 1.0.7

Grynwald.XmlDocs.MarkdownRenderer

一个库，根据 C# XML 文档注释 以及 Markdown Generator 将其转换为 Markdown

目录

• 概述
• 用法
• 许可证

概述

C# 源代码可以具有结构化的注释以提供内联 API 文档。编译器将这些注释保存为 XML 文档文件。

尽管 Grynwald.XmlDocs 包提供了一个库将此类注释解析为 .NET 对象模型，但此包增加了将包括格式化标签的 XML 文档注释转换为 Markdown 的选项。

⚠️ 注意： 此库不是一个完整的文档生成器，而旨在作为此类生成器的基础。XML 文档文件不包含程序的成员，而只包含编译器找到了任何 XML 文档注释的成员。要生成程序的完整文档，需要构建该程序的语义模型，这可以使用 Mono.Cecil 或 Roslyn (Microsoft.CodeAnalyis) 之类的库实现。

该库还无法解析对代码元素（如 <see cref="SomeClass"/>）的引用。然而，Markdown 的转换可以自定义。

用法

要将XML文档文件的 内容转换为Markdown，首先在您的项目中引用 Grynwald.XmlDocs.MarkdownRenderer 包。

使用 DocumentationFile 类加载文档文件，然后使用 MarkdownConverter 类（基于 Markdown Generator 库）将文档注释转换为Markdown区块。

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 可以将整个文档文件或仅单个成员或文本块转换为Markdown。

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");

自定义Markdown输出

Markdown转换为Markdown使用访问者模式遍历文档文件的结构。

要自定义Markdown输出，您可以创建一个自定义访问者，并将 MarkdownConverter 适配以使用该自定义访问者。

// 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);
    }
}

许可证

Grynwald.XmlDocs.MarkdownRenderer采用MIT许可证。

详细信息请见 https://github.com/ap0llo/xmldocs/blob/master/LICENSE