Test rule examples

[fisker]

It would be great if we can test examples in docs/ automatically, is this can be done?

[brettz9]

One could use a Markdown parser to grab the contents and execute those tests, though you'd need the config to be parseable.

Alternatively, https://github.com/gajus/gitdown could be used. We're using this in eslint-plugin-jsdoc to have the tests and their config/results ported into the final docs as part of a document build process. (unicorn wouldn't need to use eslint-plugin-jsdoc's approach of a single large output doc file, btw).

An advantage of having all of the samples within the test files is that it ensures they get tested, and don't need a special document build script--which may be run less frequently or tempting to run less frequently--to do the testing, yet they are addable to the docs when one wishes to update the docs.

Some don't like the fact that there are many testing examples added to the docs which may test obscure features (or coverage) and not be of interest to regular users. One could overcome this by adding a property to individual test cases to whitelist (or, if preferred, blacklist) them for inclusion in the docs.

[sindresorhus]

I don't think we should generate the doc examples from tests. I think the examples should be hand-picked.