\"Nothing is better than documentation with examples. But nothing is worse than examples that\ndon't work because the code has changed since the documentation was written.\" - rustbook
\nExample code blocks in our markdown or inline documentation comments can be useful to quickly\ndemonstrate how one can use our software. As they are part of our living standards, each example\ncode should be functional code that can be asserted and tested. Documentation example code should be\nautomated, tested and linted as part of our workflow.
\nInitially, we were thinking of creating a md-jest for parsing code blocks in markdown and transforming them into\njest tests. Similar to how ts-jest transform TS to CommonJS, but using contented-processor to transform MD files.
@eli-lim suggested we transform jest files *.test.ts into Markdown instead. We\nget the DX of writing test with Jest and IDE support (without having to support write our own runner). It is much\neasier to transform comments to markdown than transform markdown to code (although not much harder, the focus here is\non the DX). Further, you get the natural flow of writing narrative and writing tests as a narrative.
\n\nThis page, is written in a jest test file.
\nJestMarkdown.spec.ts
All comments are automatically picked up as Markdown with indent stripped. Indent are stripped using\nstrip-indent, * are also stripped. For bullet points, you should use - and avoid using * to prevent\nunintentional stripping.
// - Line Comment/* - Block Comment/** - Block CommentThis is a multi line with * stripped from each line.
This is a Line Comment
This is a Block Comment
This is a Multi Line\nBlock Comment without *.
/**\n * ### This section is generated by the code snippet below.\n *\n * This is a multi line with `*` stripped from each line.\n */\n// This is a `Line Comment`\n/* This is a `Block Comment` */\n/* This is a `Multi Line`\n `Block Comment` without `*`. */JestMarkdown has the ability to \"pickup\" codes and add them into a codeblock. Codeblock is parsed line by line,\n@contented codeblock:start indicate the starting line and @contented codeblock:end indicate the ending line.\nEverything between will be included into a codeblock. Although not recommended, you can nest multiple\n@contented codeblock between.
'@contented codeblock:start','@contented codeblock:end',it('this it statement is in a codeblock with nested codeblock', () => {\n const symbols = [\n // @contented codeblock:start\n '@contented codeblock:start',\n // @contented codeblock:end\n 'everything in between will be included as a TypeScript codeblock ```ts\\n${codes}\\n```',\n // @contented codeblock:start\n '@contented codeblock:end',\n // @contented codeblock:end\n ];\n expect(join(...symbols)).toBeDefined();\n});This Pipeline is currently in Beta!
This pipeline is considered Beta, while the idea and the intent will stay intact. We want to optimize this\npipeline for better integration with Jest. Better integration with Jest Semantic describe, it, before, and\nafter; to achieve a more natural authoring process.
Imagine the below:
\ndescribe('MyAPI: Javascript Client', () => {\n const api = new MyApi('https://my-api.com');\n\n describe('GetRecords', () => {\n it('Example', function () {\n const records = api.GetRecords(10);\n });\n });\n\n describe('PutRecord', () => {\n it('Example', async function () {\n await api.PutRecord({\n text: 'MyText',\n });\n });\n });\n});Should generate this Markdown:
\nconst api = new MyApi('https://my-api.com');const records = api.GetRecords(10);await api.PutRecord({\n text: 'MyText',\n});