byexample: free, open source tool to find snippets of code in your docs and execute them as regression tests

[Martin Di Paola]

Hi everyone, I would like to share a free, open source tool with you that
I've been developing in the last few years.

You'll be probably familiar with things like this in the Python
documentation:

```
   >>> 1 + 3
   4
```

byexample will find those snippets, it will execute "1 + 3" and the
output will be compared with the expected one (the "4") so you can know
that your docs are in sync with your code.

If you are familiar with Python's doctest module, it is the same idea
but after a few years of using it I found some limitations that I tried
to break.

That's how byexample was born: it allows you find and execute
the snippets/examples written in different languages in different files.

You could run Ruby and C++ code written in the docstrings of your Python
source code or in a fenced code block of a Markdown file.

You could "capture" the output of one example and "paste" it into
another as a way to share data between examples.

```
   $ cat somefile   # a Shell example (<foo> will capture a word)
   Lorem ipsum <foo> sit amet.

   >>> "<foo>" == "dolor"  # Python example  # byexample: +paste
   True
```

You could even "type" text when your example is interactive and requires
some input:

```
   >>> name = input("your name please: ")      # byexample: +type
   your name please: [john]

   >>> print(name)
   john
```

There are a few more features but this email is long enough.

The full set of features and tutorials are in https://byexamples.github.io
(by the way, the examples in that web page are the tests of byexample!)

Repo: https://github.com/byexamples/byexample (feel free to submit any
issue or question)

You can install it with pip:

   pip install byexample

And if you are a fan of Python's doctest (as I am), there is a
compatibility mode that you may want to check:
https://byexamples.github.io/byexample/recipes/python-doctest

I would like to receive your feedback.

Thanks for your time!
Martin.