Docfx.ResultSnippets 1.0.0

Docfx Result Snippets

• Getting Started
• Documentation

Features

• Export results to tables
• Convert Types to class diagrams
• Export results to any format supported by markdig

using Docfx.ResultSnippets;

...

// some return value
const string result = "Some result to save";
// now it can be saved as an example
result.SaveResults();
// we can also add a part to the name
"Some other result".SaveResults(partName: "part2");

Which generates a Markdown file that can be added via the include file like so,

[!INCLUDE[SomeExample](some/path/to/code/__examples__/ClassName.MethodName.{Optional-PartName}.md)]

Getting Started

To use this library, simply include Docfx.ResultSnippets.dll in your project or grab it from NuGet, and add this to the top of each .cs file that needs it:

using Docfx.ResultSnippets;

Why?

Docfx has amazing tools for including code snippets in your documentation but not the results from executing that code.

For some code examples the formatted result of executing that code is as important as the code itself.

For example code that returns an IEnumerable, the most natural way to show the result would be a table. This library provides the tools to make it happen and more.

This code,

// some complex data which will convert to a table
var data = Enumerable
    .Range(1, 3)
    .Select(
        i =>
            new
            {
                Name = $"Name {i}",
                Id = i,
                Nested = new { ChildId = i + 1 }
            }
    );
var tableResult = data.AsTableResult();

Results in this,

The aim of this library is to support Markdown friendly code results so the readers of your documentation can get a complete picture of what the code will produce. Think of it as serverside rendering of code results, like a pre executed Jupyter notebook.

For more details/information have a look the documentation, test project or create an issue.

Attributions

Icons created by juicy_fish