Support embedding of rust playpen examples which are runnable

[mdinger]

For example, just like http://rustbyexample.com/

[azerupi]

Yes, great idea :)
Have you a rough idea of how much work that represents?

Also, I have not tested extensively, but I think there is no syntax highlighting. I am not sure if the markdown crate I use supports it. Otherwise I will have pre- / post-process or use another markdown parser.

[mdinger]

Ace is the method playpen and rustbyexample use for embedding a text editor which in of itself isn't that difficult. Editor syntax highlighting is handled by ace. All you have to do is choose the theme.

Regarding processing, rustbyexample loads the examples from *.rs files and pipes them to the rust playpen via JSON api which the playpen then runs and returns output. The output is then formatted by rustbyexample and attached to the end as results I think.

Also, rustbyexample uses a {*.play} syntax for stating there is a rust file underneath which needs to be sent to playpen and loaded. So, the rust file doesn't need to be parsed out via markdown if you follow some similar course.

I hope that's helpful.

[azerupi]

Yes, thank you for the explanation.
I can't guarantee the same syntax {*.play} but I will try to see if I can make a handlebar helper.

Something that may look like:

{{#playpen example.rs}}

Would that be ok?
I am not very familiar with handlebars so I don't know what is possible and what is not.

Edit:
I also considered, letting users add their own handlebar helpers so that they can have 100% control. But I am not sure how complicated that is. If I was able to implement that, would that let you implement what you need?

[mdinger]

I don't think it's important if it is {*.play} or {{#...}} or otherwise, just that the files are loaded external from the markdown. If that uses {{...}}, that's fine.

Another thing. rustbyexample uses extensive example sets which must be testable. Currently it's done via the make build system. It'd be pretty great if mdBook made it as nice as cargo test. That may not under your control though but I thought I'd mention it.

[azerupi]

I don't really understand what you mean with the second paragraph, could you explain a little bit more?

[mdinger]

All the rustbyexample examples are composed of markdown files and rust files which makes nice documentation. The problem is when when rust is upgraded, some examples may start throwing warnings or errors when they are run because rust has been updated and some rust function was deprecated or renamed. To get around that, the make build system that is used manually searches the examples tree for rust files and compiles them with rustc to test to see if there are any warnings or errors.

Part of the problem is I think we could migrate to annotating the examples in the Cargo.toml so cargo would test them but that would require keeping two lists of examples. One for gitbook and one for cargo to test the examples with (probably in the Cargo.toml). Gfx-rs annotates their testable examples somewhat like I was thinking for example (the same in rbe would be a horrible nightmare without toml-lang/toml#235).

Anyway, what would be really nice is if it was easy to setup so that when the structure of the document was laid out, any rust files which ended up being used got compiled via cargo test. This is probably outside the scope of this problem though.

I hope that is a little more clear.

[azerupi]

Yes I understand know, but isn't that better implemented on their side?

My goal is to expose all the functionality as a library (aside from a cli) so on their side they could just add this crate to their dependencies and wrap the build in some function that executes the tests etc..

I am actually just now looking at what I should expose and how, so any feedback on that would be very useful. Once that step is done I work a little bit on the docs and I can publish a first version on Crates.io

[mdinger]

That's why I said it might not be under your control though it'd definitely be handy. Either way, it's probably outside the scope of what you'd want to do currently.

[azerupi]

Status update

In the playpen branch you can now include rust files using

{{#playpen files.rs}}

They will be displayed as all other code snippets inserted with markdown back ticks, except they have an additional playpen css class. They are not yet runnable nor editable.

If someone wants to battleproof, that would be awesome! :)

What's next?

I will begin with non editable but playable rust snippets, the rust code for this should be mostly done. Now it's mainly javascript:

• Add a play button to all code snippets with the playpen class
• Bind the click event of the play button to send Ajax request to playpen
• Add output when playpen responds

After that we can start working on editable snippets.

[azerupi]

That went a lot faster than expected :)
We now have fully runnable examples! Not yet editable though. I am going to merge this in master already, the feature, as is, could already be useful.

Editable snippets
The idea is to support both editable and non-editable code snippets that can be runned.

// Non-editable snippet
{{#playpen file.rs}}

// Editable snippet
{{#playpen file.rs editbale}}

The non editable snippets are already here, they look the same as normal code snippets except they have a play button.

For editable snippets to work there are a couple more things we need:

• Store the original code in localstorage for editable snippets, we need a way to remember which code belongs to which block
• Have a reset button
• Link in the Ace editor js and css files. I want to only include this if the page actually has a playpen snippet, to reduce load!
• Use the ace editor instead of the <pre><code> tags

Most of this should be pretty straightforward, except maybe conditionally include the ace editor if a playpen is detected.

[mdinger]

This sounds pretty great! You should add a quick example to the example docs to show it in practice if you haven't already. I'll have to check it out later.

[azerupi]

You should add a quick example to the example docs to show it in practice if you haven't already.

Yes, the only problem is that I haven't yet built in a way to escape it, soo I can't show how it is done in the docs yet ;)

I will do that now

[azerupi]

Here you go: [Doc - example](http://azerupi.github.io/mdBook/format/rust.html#Inserting runnable Rust files)

[mdinger]

That's so cool!

[mdinger]

@steveklabnik This now offers a hybrid between the book style and the rbe style because of the expansion it allows. For example, here I had to workaround the fact that the example is really huge but the important part is small. The style is to present entire examples so there isn't really a way around it. Compare with say here where the examples are compact but the actually linked to playpen example is basically useless. This would now allow the best of both worlds!

This would be much more useful to the book in general but I could still see it being useful for rbe occasionally. Very cool.

Once it supports ace, I'd start testing porting rbe to see how it works. I'm not sure I'd switch without search but it'd definitely might be worth considering.

[steveklabnik]

Oh this is amazing. 👍

[mdinger]

Has there been any change on this? Is there a way to make this editable yet? If it was, I might attempt a big port of rbe next week (no guarantees because I might be busy though). I think this was the major rbe blocker.

[azerupi]

Not really, I have been very busy with school in the last months so I didn't get the chance to work on this project.

I have some experiments in another branch but it doesn't feel right to push all the css and js onto everyone as the majority won't use it. Therefore I wanted to wait until I come up with a plug-in system where you can activate / deactivate features via the configuration file. But this essentially requires a major rewrite. I was poking at it a couple of months back but unfortunately it got sidetracked.

Now that the exam period is over I will hopefully have the time again to make progress on the rewrite.

[mdinger]

Sounds good. FWIW, I think cargo can target a specific branch (or at least a specific revision). So if progress was made to the point where rust editing is pretty decent, we could adopt it. At least, there is that possibility.

[Gordon-F]

Any updates ?

[steveklabnik]

I'm not aware of any right now, but I'd like to take a crack at it in the future.

[steveklabnik]

So, re-reading this issue, it looks like everything but editing has been implemented, right?

[azerupi]

Yes, editing like on rust-by-example requires some heavy-weight javascript and with no easy way to let the user choose what he wants I am not comfortable pushing it onto everyone. #163 would be a big step towards implementing this issue. But it requires a lot of thought and it is probably blocked on other issues.

We could implement a temporary workaround of course, a special option adding all the necessary JS.

[steveklabnik]

I don't think it's a huge priority; it'd be nice for once we get to RBE, but that's the only thing that supported it, and is not likely to get worked on for a long time.

[mraza007]

Is there something similar for python