Use "snippets" pattern to import test code into docs

[goblinfactory]

Documentation to use "snippets" to import real code from tests so that all documentation is accompanied by real working code

update to the documentation where we need better worked examples of how to create a markdown extension (component) which needs to include steps that can be verified, so that we can "prove" that the documentation is valid.
(in previous .NET projects I have worked with clients to actually have the documentation pull in the "examples" from real tests, using Simon Cropp's Markdown snippets so your documentation MUST always include real compiled, tested examples that are guaranteed to run with the latest version of the software. Documentation Pull requests are reviewed to ensure that any additional documentation is ALWAYS accompanied with a worked example. So that it's reasonable to say, if you're writing documentation to tell someone how to attach a FooA to a FooB, that you can prove that the way you're telling people how to do it, ACTUALLY works, and is up to date and current with the latest code.

With markdownsnippets; you define a snippet, anywhere in code; most often integration test code, that works as follows

// begin-snippet: MyFooSnippet
My Snippet Code
// end-snippet

then you simply import the snippet in your documentation markdown, using a token, and a pre-processor in your build step that simply does a text replace.

# some heading about Foo
Some blurb about Foo
snippet: MyFooSnippet

which after your build runs turns into

# some heading about Foo
Some blurb about Foo

    // how to add Foo to Bat
    const foo = createFoo( { .. });
    ...

Which is GUARANTEED to be the right example that works with the version of the code that your reader would download.

We dont need to use MarkdownSnippets; it's the documentation best practice that I'm advocating, not any particular technology.

Some points to note;

• Requests integration tests or integration setup that would allow for a meaningful test
• Not all code is testable in such a way that a new user would immediately be able to read a test and learn the specific concept you were or are trying to explain in documentation
• Absolutely am not suggesting a high coverage; merely that where possible, that critical documentation (where possible) should include real code examples.
• When code is NOT testable such that parts of the tests can be read by noobie users, and serve as valuable documentation artifacts, taht this should raise serious red flags about the code.
• Regarding the point above; this project has limited resources, and the energy of the founder is the most valuable, therefore my recommendation is to ONLY do this if it helps the founder, and put the founder first.
• Further to the above; It can be a huge undertaking to retroactively add tests that can be used in documentation, and that should be reconsidered after the critical project milestones are delivered.
• New code can often be written so that it can easily be tested and serve as documentation using BDD style development practices where you write your requirements in the form of documentation. i.e. a type of Documentation driven development.