Package: byexample
<!– Check that we have byexample installed first $ hash byexample #
byexample: +fail-fast–>byexamplebyexampleis 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 inPython,Rubyor
whatever in your documentation and validate them.You can always be sure that the examples are correct and your
documentation is up to date!UsageYouwrite your documentation with
examplesin a Markdown or other text file.Then, you runbyexamplefrom the command line selecting which
language or languages you want to run:Python,Ruby,ShellandC/C++to
mention a few.And yes, you can write examples in different languages in the same file.Combine them to combine their
strengthsand make your life easier.That’s all.byexamplewill compare the output of the examples with
the expected ones and it willshow any
difference.How do I get started?First, you need to install it:$ pip install byexample                # install it # byexample: +skipOr if you prefer, you can install it inside avirtual
env.If you don’t havepiporpythoninstalled, check thedownload
page.That’s it! Now, write a tutorial, a blog or a how-to and put some
examples in between (like thisREADME.mdthat 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 likePython,RubyandC++along with others.Take at look at the official web page:https://byexamples.github.ioSome quick links:Quick
usageWhere should I write the
examples?Languages supportedCurrently we support:PythonRubyJavascriptShellGDBC/C++iasmPowerShellGoRustJavaMore languages will be supported in the future. Stay tuned.Currently unsupported:ElixirPHPHelp is needed!Platforms supportedLinux is the preferable choice as it is very well tested.Since9.2.1macOS is also supported for the testing is more limited
and it is expected to have little variations from Linux.You can even runbyexamplein Windows**usingWindows
Subsystem for
Linuxbut keep in mind that the testing is even more limited; a native
execution in Windows (outside of WSL) is currently not supported.ContributingFirst off, thanks for using and considering contributing tobyexample.We love to receive contributions from our community. There are tons of
ways you can contributeadd support to new languages (Javascript, Julia, just listen to you
heart). Check thishow
to.misspelling? Improve to the documentation is more than welcome.add more examples. How do you usebyexample? Give us your
feedback!isbyexampleproducing 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 ourCONTRIBUTINGguidelines and welcome!ExtendbyexampleIt is possible to extendbyexampleadding 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 outhow to support new finders and
languagesandhow to hook to events with
concernsfor a quick tutorials that shows exactly how to do that.You could also share your work andcontributetobyexamplewith your extensions.VersioningWe usesemantic versionfor 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
offeranyguarantees.Contributions from the community are
needed!See the latestreleases and
tagsand thechangelogCurrent version:$byexample-Vbyexample10.5.6(Python<...>)-GNUGPLv3<...>Copyright(C)DiPaolaMartin-https://byexamples.github.io<...>LicenseThis project is licensed under GPLv3$head-n2LICENSE# byexample: +norm-wsGNUGENERALPUBLICLICENSEVersion3,29June2007SeeLICENSEfor more details.