Example decorators

[Bzero]

This PR resolves #503, implements the @example decorator and adds basic examples to most standard library functions.

The @example decorator takes the example code as the first positional argument and optionally an example description as second argument. Multiple examples can be defined by using @example multiple times:

@example("example_function(0)")
@example("example_function(1)", "Evaluate the function at $1$.")
fn example_function(x) = x

At the moment the examples are only used to compile the documentation, however it might be nice to make them accessible in the CLI or web interface in the future. In the documentation the example code is run trough the Numbat interpreter and is shown together with the results as if it was typed in the CLI interface. Additionally the example description is displayed (if available) and a "Run this example" link is shown. Since the examples can be a bit lengthy, I chose to display them collapsed by default.

I have not added any examples to non pure functions like random(), or now() for the moment. While this would work in principle, it would modify the documentation every time someone re-runs book/build.py which doesn't feel very practical.

[sharkdp]

Great work, as always! Thank you. It might take a while (> 2 weeks) before I can do a full review.

[Bzero]

Of course, take your time!

[sharkdp]

Thank you for the update. Will continue my review over the next days.

This is great!

[sharkdp]

Can we please move the "Run this example" links below the code snippets? I think that would look better because the "play" icons wouldn't line up with the bullets. And most of the time, users will only read the example output instead of trying it interactively.

[Bzero]

Sure, that is fine for me.

[Bzero]

Actually, after trying it out I think it doesn't look exactly nice with the "Run this example" links below the code snippets either, at least when there is no example description. Maybe we should not use a bullet list here at all.

[Bzero]

I changed the display and tried to mimic the mdBook Rust Playground feature "play button":

The implementation is a little hacky as it requires to insert html code blocks in the markdown documents, however since they are entirely autogenerated I think it should be okay.

[sharkdp]

Really nice! Thank you 👍

[sharkdp]

I finished my review. Again: thank you very much for implementing this — and adding examples to all existing functions!

[Bzero]

I finished my review. Again: thank you very much for implementing this — and adding examples to all existing functions!

Thanks a lot for the review.