Embedding Code Samples Edit on GitHub

The primary author of Storyteller once had a very bad experience when a huge technical documentation effort failed to keep pace with an evolving codebase. To eliminate that issue permanently, Storyteller supports a feature where you can pull code samples from the actual codebase at documentation generation time to keep the documentation in sync with a changing API.

How it Works

Storyteller simply scans code files looking for comments that match this basic pattern (for C#):

// SAMPLE: [SnippetName]

Some C# CODE

// ENDSAMPLE

In the usage above, the text after // SAMPLE: is the name of the snippet we'll refer to later. The // SAMPLE: and // ENDSAMPLE comments establish the boundaries of a code snippet within the larger code file.

When the Storyteller documentation preview mode or publishing is running, Storyteller reads all the code files in the directories you specified to search (or /src as the default) looking for code sample comments.

As part of the topic generation, code samples are embedded into the markdown files like this:

<[sample:registering-custom-runtime-converter]>

That code above is rendered into a topic page using the Prism.js library to look like this:

public CellHandling Start()
{
    var handling = CellHandling.Basic();

    // Adding a system wide list. 
    handling.AddSystemLevelList("positions", new[] {"LB", "OL", "DL", "WR", "RB"});

    // This is where you can register a custom runtime conversion
    handling.RegisterRuntimeConversion<PlayerConverter>();

    return handling;
}

Enabling Samples in your Project

To enable the code sample formatting with Prism.js, you need to reference both prism.js and prism.css. See the Prism.js website to build out your own version or grab the ones from Storyteller to use the same theme shown above.

Language Support

The language support is relatively easy to extend if there's a missing language you would want to use -- and we would be happy to take pull requests for it. For the moment, the languages below are the only ones supported (Ruby, Razor, and Spark were cut from the previous tooling this was taken from).

C#

Storyteller will look in files with the extension *.cs for snippets that follow this pattern:

// SAMPLE: [SnippetName]
Some C# CODE
// ENDSAMPLE

Javascript

Storyteller will look in files with the extension *.js for snippets that follow this pattern:

// SAMPLE: [SnippetName]
Some JavaScript Code
// ENDSAMPLE

Html

Storyteller will look in files with the extension *.htm or *.html for snippets that follow this pattern:

<!-- SAMPLE: [SnippetName] -->
Some Html markup
<!-- ENDSAMPLE -->

Xml

Storyteller will look in files with the extension *.xml for snippets that follow this pattern:

<!-- SAMPLE: [SnippetName] -->
Xml Data
<!-- ENDSAMPLE -->

CSS

Storyteller will look in files with the extension *.css for snippets that follow this pattern:

/* SAMPLE: [SnippetName] */
Stylesheet Markup
/* ENDSAMPLE */