Run and Edit examples

[habere-et-dispertire]

Run and Edit Examples

Please consider making examples that we can run and edit.
CodeAPI is an example of something that enables this.
I see this as a fundamental step towards an explorable explanation.

Try codeapi's playground if you like -- it's running 2024.09.

A raku sandbox has been recently added following 2024.09.

If codeapi doesn't load then by graceful degradation the static example remains.

[librasteve]

I feel that a code example gadget is problematic for documentation. There are two aspects to my concern:

1. content / design

The focus of a good docs site is to have the cleanest, most comprehensible and easily navigated documents to help users to find definitive answers to “how to” questions and as a reference for corner case examples.

Sadly we have a lot of work to do with the Raku docs to achieve this. A code sandbox gadget is a major distraction from this challenging focus, both in terms of the effort of making it work and fitting a modem, responsive design, having Rainbow code highlighting and in terms of the defocusing in the site user experience.

2. technical

You mention a potential 3rd party frame embeddable solution. Yet we have no control over the backend infrastructure, the performance and availablility and reachability of this service. What happens if a malicious actor applies a ddos attack? How can you work with libraries?

The https://raku.org site already signposts a couple of well established online sandbox tools and in the most part having a window to one of these open (or raku in an IDE on your machine) is a better alternative to a gadget popup or iframe shoehorned in to the reference document.

Less is More

[habere-et-dispertire]

I agree with your sentiments as does Antoine de Saint Exupéry:

Il semble que la perfection soit atteinte non quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à retrancher.
It seems that perfection is attained not when there is nothing more to add, but when there is nothing more to remove.
🙏

The suggested workaround was intended as but a proof of concept illustrating functionality.
I still imagine that dogfooding examples would be a wonderful writer's aid turning it into a living document with an automatic guard against bitrot while increasing consistency and accuracy. It need not be exposed to the reader.

One avenue I peaked into was using markdown with pandoc and a lua filter to run and inject output of raku fenced code blocks. Maybe rakudoc functionality already includes something similar?

Thank you for your words.
👍