Add ability to run code examples in the playground

[SeanTAllen]

We had this sort of on the old tutorial but that didn't get migrated over.

[SeanTAllen]

I went looking through the mkdocs material for this functionality and didn't see it. I'm going to reach out to the author and see if I missed the functionality, otherwise, I'll put in a feature request.

[SeanTAllen]

So this is the report:

We can do some custom css and javascript. That's not really my thing, but someone could take this on.

squidfunk/mkdocs-material#3563

[shaedrich]

There doesn't seem to be a native option to add any other button than "copy" and "select" with the latter being sponsors-only:

I went looking through the mkdocs material for this functionality and didn't see it. I'm going to reach out to the author and see if I missed the functionality, otherwise, I'll put in a feature request.

Others have also wished for this functionality to become more generalized: squidfunk/mkdocs-material#4005 The only solution given there is to fork the theme.

However, one could add custom JavaScript to add this behavior: https://squidfunk.github.io/mkdocs-material/customization/#additional-javascript

To achieve a quick and easy solution, we could add buttons to all code blocks manually

Something, that would be more work but would prevent us from duplicating the code (once inside the code block and once URL-encoded in the button), would be to move the code to separate files and embed them. Alternatively, it could be gists.

This could also help in cases where the examples are longer than the URL is allowed to be by the browser (I don't know if we would run into that problem) 🤔

Or should the preview be in the tutorial, not just (in a new tab) in the playground?

[SeanTAllen]

We use the insiders build. So that is available as an option.

[shaedrich]

Yeah, but that is only the "select" button, not the "play"/"run"/"execute" button

[jemc]

The other nice thing about the idea of moving the code examples to separate Pony files, is that we easily could start including testing to prove that all the examples compile.

[shaedrich]

If it helps, this can be done in a separate PR, when other questions are not yet answered

[SeanTAllen]

@shaedrich are you interesting in tackling this? if yes, what additional information or discussion do you need from us?

[shaedrich]

@SeanTAllen I am indeed. The questions asked above still stand:

• tutorial code examples inline, as separate files (still everything in one place), or as gist?
• playground preloaded code inline (URLs might get too long), via gist (already implemented), or via file (see above, not implemented yet, afaik)?
• "Play"/"Run"/"Exec" button in tutorial separately below the code block (custom code) or in the top right corner as part of the editor widget (might be a little more complicated)?

[SeanTAllen]

I'd prefer

• separate files but...
• it seems like gist is the only reasonable solution at this time
• "all other things being more or less equal" i would go with "whatever you think is easiest to maintain"

my worry with gists is... that seems hard to maintain as the code is "somewhere else". which i think means, yes files is best. Looking at the tutorial I seriously doubt any of our code is going to hit a URL limit so...

I'd love to see the code stored in files and then the content put into the block at build time. then we can use ponyc to verify that all the code samples build. we can have the code inline in the block in the built site and do preloaded code inline. given that our code samples are in the hundreds to low thousands for the examples, i think that would work.

@jemc what are your thoughts?

[shaedrich]

it seems like gist is the only reasonable solution at this time

Grabbing the code from files could easily be implemented here:

https://github.com/ponylang/pony-playground/blob/59b1ffdac935f27cd73d7fd77ff380e7a38e9b7d/static/web.js#L516-L527

I'd love to see the code stored in files and then the content put into the block at build time.

There's even an option to embed external files in the code block widget: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files

[jemc]

Yes, if it's possible I'd want the code to be in files in this repo (rather than gists) and get incorporated at tutorial build time. And get tested with ponyc at CI time.

[shaedrich]

Status update

1. ✅ Move code samples to separate files: [1/?] Add ability to run code examples in the playground: Move code samples to separate files #544
2. ✅ Code samples extended to be runnable: [2/?] Add ability to run code examples in the playground: Extend code samples to be runnable #545
3. ⏳ Fetch tutorial snippet from URL by file name: [3/?] Add ability to run code examples in the playground: Fetch tutorial snippet from URL by file name #542 and [3/?] Add ability to run code examples in the playground: Fetch tutorial snippet from URL by file name pony-playground#205
4. ❓ Get pony snippets tested with ponyc at CI time: [4/?] Add ability to run code examples in the playground: Get pony snippets tested with ponyc at CI time #550
5. ⏳ Display code block result directly below code block on tutorial site: [5/?] Add ability to run code examples in the playground: Add CORS exception for tutorial.ponylang.io to route /evaluate.json pony-playground#212 and [5/?] Add ability to run code examples in the playground: Run code samples inline #554

[shaedrich]

Possible follow-up features

• ⌛ Toggle code snippets in tutorial to see the full source code (e.g. example.pony) that will be executed in the playground, optionally highlighting the relevant lines from the snippet (e.g. example.pony:4:8): Show full program in tutorial with highlighted lines #552
• ⌛ Highlight actual snippet lines in playground (using editShowRegion()) (e.g. example.pony:4:8): Show highlighted lines from snippet pony-playground#231
• ⌛ Making snippets interactive (adding comments with little tasks): Make snippets interactive with annotations #553
• This could be thought even further, as we will already have implemented validation in step 4 (see above), to validate if the user completed the task. Examples would be:
  • Code snippet fails, make it succeed
  • then is outputted, make it output else
• ⌛ Link back from the playground to the tutorial page when snippet is passed via URL: Add docs button to playground pony-playground#230
  

→ Custom code fence: #555

[shaedrich]

• ❓ Get pony snippets tested with ponyc at CI time → I still need to figure out, how that might work 🤔 If there's someone else who would take this on, I wouldn't be mad 😅

From #549:

Where do we put the expectations for stdOut, stdErr, and exitCode? Because if we don't do that, only snippets that print to stdOut could be tested

[shaedrich]

• ❓ Get pony snippets tested with ponyc at CI time → I still need to figure out, how that might work 🤔 If there's someone else who would take this on, I wouldn't be mad 😅

From #549:

Where do we put the expectations for stdOut, stdErr, and exitCode? Because if we don't do that, only snippets that print to stdOut could be tested

See #550 for a possible implementation

[shaedrich]

One thing, I just thought about: When we have a snippet should there still be an option to create a gist from that? That seems to be a little redundant 🤔

[jemc]

Discussed on the sync call - while it isn't super helpful to anyone to create a few gist from a github-sourced snippet, it's not a problem per se, and it would potentially be confusing (or a maintenance problem) to add special case behavior to disable that.