4 ms·

Would be great to have a dynamic Readme generated from tests (eg. RSpec etc...)

kemitchell 6y ago
For sufficiently small libraries, I've done a number of READMEs with usage examples that include test assertions. The examples then serve as the test suite. For example: https://www.npmjs.com/package/spdx-expression-parse https://www.npmjs.com/package/spdx-expression-parse I've released free scripts for Node.js that do the job of parsing the Markdown, extracting fenced code blocks, and filtering by infostring. That leaves just lines of code, which you can pipe straight to the Node interpreter: https://www.npmjs.com/package/defence-cli https://www.npmjs.com/package/defence-cli
thisrod 6y ago
Literate.jl comes close. You maintain a file README.jl, with a mixture of Markdown text, example code in Julia, and hidden code in Julia. Inspired by Knuth's literate programming idea, there are several things you can do with that file: * Weave it to get README.md, with the text, the example code, and the output from running the example code. * #include it in your tests, to run the example code, then run the hidden code to verify the results. * Super-weave it to generate a web notebook, where people can modify the example code and see what happens. This isn't perfect. When the examples generate graphical output, you have to write some boilerplate code to capture it as a GIF and link it in README.md. That gets annoying in a numerical language like Julia. But it's pretty good.
pydry 6y ago
I wrote a specification-test framework that does this: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory Project with README that is partially generated from the code samples in the tests: https://github.com/crdoconnor/strictyaml https://github.com/crdoconnor/strictyaml with the README template: https://github.com/crdoconnor/strictyaml/blob/master/docs/index.md https://github.com/crdoconnor/strictyaml/blob/master/docs/in... that grabs code snippets and their expected outputs from the story: https://github.com/crdoconnor/strictyaml/blob/master/hitch/story/quickstart.story https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...
throw_m239339 6y ago
You can kind of do that with Go with "example" tests and Godoc. In Go, tests can just be code snippets demonstrating the usage of an API. But ultimately, isn't it what TDD is about? Thinking about the public API before implementation in order to focus on what matters?

For sufficiently small libraries, I've done a number of READMEs with usage examples that include test assertions. The examples then serve as the test suite. For example: https://www.npmjs.com/package/spdx-expression-parse https://www.npmjs.com/package/spdx-expression-parse I've released free scripts for Node.js that do the job of parsing the Markdown, extracting fenced code blocks, and filtering by infostring. That leaves just lines of code, which you can pipe straight to the Node interpreter: https://www.npmjs.com/package/defence-cli https://www.npmjs.com/package/defence-cli

thisrod 6y ago

Literate.jl comes close. You maintain a file README.jl, with a mixture of Markdown text, example code in Julia, and hidden code in Julia. Inspired by Knuth's literate programming idea, there are several things you can do with that file: * Weave it to get README.md, with the text, the example code, and the output from running the example code. * #include it in your tests, to run the example code, then run the hidden code to verify the results. * Super-weave it to generate a web notebook, where people can modify the example code and see what happens. This isn't perfect. When the examples generate graphical output, you have to write some boilerplate code to capture it as a GIF and link it in README.md. That gets annoying in a numerical language like Julia. But it's pretty good.

pydry 6y ago

I wrote a specification-test framework that does this: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory Project with README that is partially generated from the code samples in the tests: https://github.com/crdoconnor/strictyaml https://github.com/crdoconnor/strictyaml with the README template: https://github.com/crdoconnor/strictyaml/blob/master/docs/index.md https://github.com/crdoconnor/strictyaml/blob/master/docs/in... that grabs code snippets and their expected outputs from the story: https://github.com/crdoconnor/strictyaml/blob/master/hitch/story/quickstart.story https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...

throw_m239339 6y ago

You can kind of do that with Go with "example" tests and Godoc. In Go, tests can just be code snippets demonstrating the usage of an API. But ultimately, isn't it what TDD is about? Thinking about the public API before implementation in order to focus on what matters?