Metadata-Version: 2.2
Name: byexample
Version: 11.0.0
Summary: Write snippets of code in C++, Python, Ruby, and others as documentation and execute them as regression tests.
Home-page: https://byexamples.github.io
Author: Di Paola Martin
Author-email: use-github-issues@example.com
License: GNU GPLv3
Keywords: doctest documentation test testing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Testing
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Other
Classifier: Programming Language :: Other Scripting Engines
Classifier: Programming Language :: PHP
Classifier: Programming Language :: Ruby
Classifier: Programming Language :: Unix Shell
Requires-Python: >=3.7
License-File: LICENSE
Requires-Dist: pexpect<5,>=4
Requires-Dist: appdirs<2,>=1.4.3
Requires-Dist: termscraper<0.11,>=0.10
Requires-Dist: bracex<3,>=2.1.0
Requires-Dist: importlib-resources<6.0.0,>=5.5.0
Requires-Dist: tqdm<5,>=4
Requires-Dist: pygments<3,>=2
Requires-Dist: argcomplete<2.1.0,>=2.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<!– Check that we have byexample installed first $ hash byexample #
byexample: +fail-fast

–>

``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.

Do not <i>write</i> tests: write what you want, what do you expect, make
examples of them. Let ``byexample`` <b>turn them</b> in your tests.

You can always be <b>sure</b> that the examples are correct and your
documentation is up to date!

Usage
-----



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>`__.

How do I get started?
---------------------

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>`__

Languages supported
-------------------

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!

Platforms supported
-------------------

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.

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://byexamples.github.io/byexample/contrib/how-to-support-new-finders-and-languages>`__.
-  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://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 11.0.0 (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.
