Write snippets of code in C++, Python, Ruby, and others as documentation and execute them as regression tests.
<!– Check that we have byexample installed first $ hash byexample # byexample: +fail-fast
–>
byexamplebyexample 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!
You write your documentation with examples <https://byexamples.github.io/byexample/overview/where-should-I-write-the-examples>__
in a Markdown or other text file.
Then, you run byexample from the command line selecting which
language or languages you want to run:
Python <https://byexamples.github.io/byexample/languages/python>,
Ruby <https://byexamples.github.io/byexample/languages/ruby>,
Shell <https://byexamples.github.io/byexample/languages/shell>__ and
C/C++ <https://byexamples.github.io/byexample/languages/cpp>__ to
mention a few.
And yes, you can write examples in different languages in the same file.
Combine them to combine their strengths <https://byexamples.github.io/byexample/recipes/advanced-checks>__
and make your life easier.
That’s all. byexample will compare the output of the examples with
the expected ones and it will show any difference <https://byexamples.github.io/byexample/overview/differences>__.
First, you need to install it:
::
$ pip install 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.
::
$ byexample -l python,ruby,shell README.md # run it # byexample: +skip [PASS] Pass: <...> Fail: <...> Skip: <...>
Several languages are supported like Python, Ruby and C++
along with others.
Take at look at the official web page: https://byexamples.github.io
Some quick links:
Quick usage <https://byexamples.github.io/byexample/overview/usage>__Where should I write the examples? <https://byexamples.github.io/byexample/overview/where-should-I-write-the-examples>__Currently we support:
Python <https://byexamples.github.io/byexample/languages/python>__Ruby <https://byexamples.github.io/byexample/languages/ruby>__Javascript <https://byexamples.github.io/byexample/languages/javascript>__Shell <https://byexamples.github.io/byexample/languages/shell>__GDB <https://byexamples.github.io/byexample/languages/gdb>__C/C++ <https://byexamples.github.io/byexample/languages/cpp>__iasm <https://byexamples.github.io/byexample/languages/iasm>__PowerShell <https://byexamples.github.io/byexample/languages/powershell>__Go <https://byexamples.github.io/byexample/languages/go>__Rust <https://byexamples.github.io/byexample/languages/rust>__Java <https://byexamples.github.io/byexample/languages/java>__More languages will be supported in the future. Stay tuned.
Currently unsupported:
Elixir <https://byexamples.github.io/byexample/languages/elixir>__PHP <https://byexamples.github.io/byexample/languages/php>__Help is needed!
Linux is the preferable choice as it is very well tested.
Since 9.2.1 macOS is also supported for the testing is more limited
and it is expected to have little variations from Linux.
You can even run byexample in Windows\ ** using Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>__
but keep in mind that the testing is even more limited; a native
execution in Windows (outside of WSL) is currently not supported.
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
how to <https://byexamples.github.io/byexample/contrib/how-to-support-new-finders-and-languages>__.byexample? Give us your
feedback!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://byexamples.github.io/byexample/contrib/how-to-support-new-finders-and-languages>`__
and `how to hook to events with
concerns <https://byexamples.github.io/byexample/contrib/how-to-hook-to-events-with-concerns>`__
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).
- ``provisional``: 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.
- ``unsupported``: it may work but currently it is not possible to
offer *any* guarantees. `Contributions from the community are
needed! <https://github.com/byexamples/byexample/tree/master/CONTRIBUTING.md>`__
See the latest `releases and
tags <https://github.com/byexamples/byexample/tags>`__ and the
`changelog <https://github.com/byexamples/byexample/releases>`__
Current version:
.. code:: shell
$ byexample -V
byexample 10.5.6 (Python <...>) - GNU GPLv3
<...>
Copyright (C) Di Paola Martin - https://byexamples.github.io
<...>
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.
FAQs
Write snippets of code in C++, Python, Ruby, and others as documentation and execute them as regression tests.
We found that byexample demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.