Write snippets of code in C++, Python, Ruby, and others as documentation and execute them as regression tests.
Project description
``byexample``
=============
``byexample`` is a literate programming engine where you mix ordinary
text and snippets of code in the same file and then you execute them as
regression tests.
It lets you to execute the examples written in ``Python``, ``Ruby`` or
whatever in your documentation and validate them.
You can always be sure that the examples are correct and your
documentation is up to date!
If not, you may have an out dated documentation or your docs are ok but
you have a bug in your code.
Usage
-----
.. raw:: html
<img src="https://raw.githubusercontent.com/byexamples/byexample/master/media/demo.gif" alt="Sorry, it seems that you cannot see the demo. Another excuse to install byexample and test it by yourself ;)" width="75%" height="75%">
How do I get started?
---------------------
First, you need to install it locally.
.. code:: shell
$ pip install --user byexample # install it # byexample: +skip
Or if you prefer, you can install it inside a `virtual
env <https://docs.python.org/3/library/venv.html>`__.
If you don't have ``pip`` or ``python`` installed, check the `download
page <https://www.python.org/downloads/>`__.
That's it! Now, write a tutorial, a blog or a how-to and put some
examples in between (like this ``README.md`` that you are reading); All
the snippets and examples will be collected, executed and checked.
.. code:: shell
$ byexample -l python,ruby,shell README.md # run it # byexample: +skip
[PASS] Pass: <...> Fail: <...> Skip: <...>
You can select which languages to run, over which files, how to display
the differences and much more.
The
`usage <https://github.com/byexamples/byexample/tree/master/docs/usage.md>`__
document goes through almost all the flags that ``byexample`` program
has, full of examples of course.
What an example looks like?
---------------------------
It is just a snippet of code followed by the expected result:
.. code:: python
>>> 1 + 2
3
or
.. code:: python
1 + 2
out:
3
The expression ``1 + 2`` is executed and the output compared with ``3``
to see if the test passes or not.
Where should I write the examples?
----------------------------------
``byexample`` really doesn't care where you write the examples: you can
write them in a Markdown, HTML, Latex, or plain text file.
Even you can write them in your own source code to document and test it.
Anything that it is between `````<language>`` and ``````` is considered
an example: this the Markdown fenced block syntax.
But ``byexample`` detects examples in other contexts as well.
For example in ``Python`` you can use the prompts ``>>>`` and ``...`` to
write an interpreter session like example.
.. code:: python
>>> def add(a, b):
... return a + b
>>> add(1, 2)
3
Take a look to the documentation of each language
`docs/languages <https://github.com/byexamples/byexample/tree/master/docs/languages/>`__.
Languages supported
-------------------
Currently we support:
- Python (compatible with ``doctest``) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/python.md>`__
- Ruby ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/ruby.md>`__
- Shell (``sh`` and ``bash``) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/shell.md>`__
- GDB (the `GNU
Debugger <https://www.gnu.org/software/gdb/download/>`__) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/gdb.md>`__
- C++ (using `cling <https://github.com/root-project/cling>`__ -
*experimental*) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/cpp.md>`__
More languages will be supported in the future. Stay tuned.
Contributing
------------
First off, thanks for using and considering contributing to
``byexample``.
We love to receive contributions from our community. There are tons of
ways you can contribute
- add support to new languages (Javascript, Julia, just listen to you
heart). Check this `how
to <https://github.com/byexamples/byexample/tree/master/docs/how_to_support_new_finders_and_languages.md>`__.
- misspelling? Improve to the documentation is more than welcome.
- add more examples. How do you use ``byexample``? Give us your
feedback!
- is ``byexample`` producing a hard-to-debug diff or you found a bug?
Create an issue in github.
But don't be limited to those options. We keep our mind open to other
useful contributions: write a tutorial or a blog, feature requests,
social media...
Check out our
`CONTRIBUTING <https://github.com/byexamples/byexample/tree/master/CONTRIBUTING.md>`__
guidelines and welcome!
Extend ``byexample``
~~~~~~~~~~~~~~~~~~~~
It is possible to extend ``byexample`` adding new ways to find examples
in a document and/or to parse and run/interpret a new language or adding
hooks to be called regardless of the language/interpreter.
Check out `how to support new finders and
languages <https://github.com/byexamples/byexample/tree/master/docs/how_to_support_new_finders_and_languages.md>`__
and `how to hook to events with
concerns <https://github.com/byexamples/byexample/tree/master/docs/how_to_hook_to_events_with_concerns.md>`__
for a quick tutorials that shows exactly how to do that.
You could also share your work and
`contribute <https://github.com/byexamples/byexample/tree/master/CONTRIBUTING.md>`__
to ``byexample`` with your extensions.
Versioning
----------
We use `semantic version <https://semver.org/>`__ for the core or
engine.
For each module we have the following categorization:
- ``experimental``: non backward compatibility changes are possible or
even removal between versions (even patch versions).
- ``unstable``: low impact non backward compatibility changes may occur
between versions; but in general a change like that will happen only
between major versions.
- ``stable``: non backward compatibility changes, if happen, they will
between major versions.
- ``deprecated``: it will disappear in a future version.
See the latest `releases and
tags <https://github.com/byexamples/byexample/tags>`__
Current version:
.. code:: shell
$ byexample -V
byexample 7.1.2 - GNU GPLv3
<...>
Copyright (C) Di Paola Martin - https://github.com/byexamples/byexample
<...>
License
-------
This project is licensed under GPLv3
.. code:: shell
$ head -n 2 LICENSE # byexample: +norm-ws
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
See
`LICENSE <https://github.com/byexamples/byexample/tree/master/LICENSE.md>`__
for more details.
=============
``byexample`` is a literate programming engine where you mix ordinary
text and snippets of code in the same file and then you execute them as
regression tests.
It lets you to execute the examples written in ``Python``, ``Ruby`` or
whatever in your documentation and validate them.
You can always be sure that the examples are correct and your
documentation is up to date!
If not, you may have an out dated documentation or your docs are ok but
you have a bug in your code.
Usage
-----
.. raw:: html
<img src="https://raw.githubusercontent.com/byexamples/byexample/master/media/demo.gif" alt="Sorry, it seems that you cannot see the demo. Another excuse to install byexample and test it by yourself ;)" width="75%" height="75%">
How do I get started?
---------------------
First, you need to install it locally.
.. code:: shell
$ pip install --user byexample # install it # byexample: +skip
Or if you prefer, you can install it inside a `virtual
env <https://docs.python.org/3/library/venv.html>`__.
If you don't have ``pip`` or ``python`` installed, check the `download
page <https://www.python.org/downloads/>`__.
That's it! Now, write a tutorial, a blog or a how-to and put some
examples in between (like this ``README.md`` that you are reading); All
the snippets and examples will be collected, executed and checked.
.. code:: shell
$ byexample -l python,ruby,shell README.md # run it # byexample: +skip
[PASS] Pass: <...> Fail: <...> Skip: <...>
You can select which languages to run, over which files, how to display
the differences and much more.
The
`usage <https://github.com/byexamples/byexample/tree/master/docs/usage.md>`__
document goes through almost all the flags that ``byexample`` program
has, full of examples of course.
What an example looks like?
---------------------------
It is just a snippet of code followed by the expected result:
.. code:: python
>>> 1 + 2
3
or
.. code:: python
1 + 2
out:
3
The expression ``1 + 2`` is executed and the output compared with ``3``
to see if the test passes or not.
Where should I write the examples?
----------------------------------
``byexample`` really doesn't care where you write the examples: you can
write them in a Markdown, HTML, Latex, or plain text file.
Even you can write them in your own source code to document and test it.
Anything that it is between `````<language>`` and ``````` is considered
an example: this the Markdown fenced block syntax.
But ``byexample`` detects examples in other contexts as well.
For example in ``Python`` you can use the prompts ``>>>`` and ``...`` to
write an interpreter session like example.
.. code:: python
>>> def add(a, b):
... return a + b
>>> add(1, 2)
3
Take a look to the documentation of each language
`docs/languages <https://github.com/byexamples/byexample/tree/master/docs/languages/>`__.
Languages supported
-------------------
Currently we support:
- Python (compatible with ``doctest``) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/python.md>`__
- Ruby ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/ruby.md>`__
- Shell (``sh`` and ``bash``) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/shell.md>`__
- GDB (the `GNU
Debugger <https://www.gnu.org/software/gdb/download/>`__) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/gdb.md>`__
- C++ (using `cling <https://github.com/root-project/cling>`__ -
*experimental*) ->
`docs <https://github.com/byexamples/byexample/tree/master/docs/languages/cpp.md>`__
More languages will be supported in the future. Stay tuned.
Contributing
------------
First off, thanks for using and considering contributing to
``byexample``.
We love to receive contributions from our community. There are tons of
ways you can contribute
- add support to new languages (Javascript, Julia, just listen to you
heart). Check this `how
to <https://github.com/byexamples/byexample/tree/master/docs/how_to_support_new_finders_and_languages.md>`__.
- misspelling? Improve to the documentation is more than welcome.
- add more examples. How do you use ``byexample``? Give us your
feedback!
- is ``byexample`` producing a hard-to-debug diff or you found a bug?
Create an issue in github.
But don't be limited to those options. We keep our mind open to other
useful contributions: write a tutorial or a blog, feature requests,
social media...
Check out our
`CONTRIBUTING <https://github.com/byexamples/byexample/tree/master/CONTRIBUTING.md>`__
guidelines and welcome!
Extend ``byexample``
~~~~~~~~~~~~~~~~~~~~
It is possible to extend ``byexample`` adding new ways to find examples
in a document and/or to parse and run/interpret a new language or adding
hooks to be called regardless of the language/interpreter.
Check out `how to support new finders and
languages <https://github.com/byexamples/byexample/tree/master/docs/how_to_support_new_finders_and_languages.md>`__
and `how to hook to events with
concerns <https://github.com/byexamples/byexample/tree/master/docs/how_to_hook_to_events_with_concerns.md>`__
for a quick tutorials that shows exactly how to do that.
You could also share your work and
`contribute <https://github.com/byexamples/byexample/tree/master/CONTRIBUTING.md>`__
to ``byexample`` with your extensions.
Versioning
----------
We use `semantic version <https://semver.org/>`__ for the core or
engine.
For each module we have the following categorization:
- ``experimental``: non backward compatibility changes are possible or
even removal between versions (even patch versions).
- ``unstable``: low impact non backward compatibility changes may occur
between versions; but in general a change like that will happen only
between major versions.
- ``stable``: non backward compatibility changes, if happen, they will
between major versions.
- ``deprecated``: it will disappear in a future version.
See the latest `releases and
tags <https://github.com/byexamples/byexample/tags>`__
Current version:
.. code:: shell
$ byexample -V
byexample 7.1.2 - GNU GPLv3
<...>
Copyright (C) Di Paola Martin - https://github.com/byexamples/byexample
<...>
License
-------
This project is licensed under GPLv3
.. code:: shell
$ head -n 2 LICENSE # byexample: +norm-ws
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
See
`LICENSE <https://github.com/byexamples/byexample/tree/master/LICENSE.md>`__
for more details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
byexample-7.1.2.tar.gz
(58.1 kB
view hashes)
Built Distribution
Close
Hashes for byexample-7.1.2-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2964b70ff74699d10e5a5ad73509248a23bd73ed0397aaf5d05cc917dbce1fea |
|
| MD5 | 3ce9e4bf136fde62c29d8083adf55582 |
|
| BLAKE2b-256 | 011c9f4abf0bd98830ab6b7e930237862bd0191db47e9af0c10a6485f6e81014 |
