Documentation: Add polyglot specs to example gallery ?

The Clojure Data Science community is making heavy use of vega lite for plotting. It has become the dominant technology for doing plots in Clojure.

The adaption of vega (lite) in Clojure would be eased if there would be somewhere a gallery of examples, using the Clojure syntax for the Json lite specs, as an example:

{:$schema "https://vega.github.io/schema/vega-lite/v5.json"
 :data {:url "data/cars.json"}
 :description "A scatterplot showing horsepower and miles per gallons for various cars."
 :encoding {:x {:field "Horsepower" :type "quantitative"}
            :y {:field "Miles_per_Gallon" :type "quantitative"}}
 :mark "point"}

We could either create an Clojure specific example galery ourselves (reusing/copying the VL examples content of this repository), or the official example gallery could be changed, to become “polyglot”, so showing the examples “not only in Json”.

This could be done similar to some "polyglot examples of some APIs, just for illustration:

My question / proposal would be if you think it would be a good idea to change basically all the “individual example web pages”, like: https://vega.github.io/vega-lite/examples/point_2d.html

to become “polyglot” and show the example not only in Json.

Clojure could be a first starting point.

[domoritz]

Thank you for your comment @kanitw. I absolutely agree that we need to keep the maintenance burden for the core developers low.

I’m not sure a transpiler will completely eliminate that overhead, though. We will still get issues against the examples even if they are generated by a transpiler. So whether we use a transpiler or hard-coded examples (pulled in from another repo so we move issues there?) doesn’t make a huge difference to me. I do prefer a transpiler, though, since it would automatically work for all examples. You have a good point, though, that we don’t want to have to review pull requests so I also agree with you now to pull the examples out into another repo.

I agree that we do need a fully automated process built into the site build script. That’s going to take some digging into the build scripts and GitHub actions and is not something the core developers will have time for (but are of course happy to help with any advice!).

[jwoLondon]

Good to see the number of languages expanding. I can see the logic of a transpiler solution for several of them as the ‘other’ language can map well onto its Vega-Lite JSON equivalent. I can also see the reason to avoid a PR-per-example solution which is clearly not scalable for the core team.

I develop (and have done for the last 4 years), a parallel set of examples in the Elm language (and also do the same for Vega). Additionally I have a set of literate visualization examples that map closely to the vega-lite examples. For elm-vegalite at least, I don’t think a transpiler solution would work. Not only because there are a few differences that aren’t easily mapped computationally, but also to take advantage of the language, one might deliberately chose a different approach (e.g. perform data-shaping externally rather than as a Vega-lite transform).

I wonder therefore if a slightly more flexible approach would be to have pointers on the main Vega-Lite page to other ‘approved’ language versions, that may in some cases be the transpiled examples, in others to approved repos or web pages. This would require a one-off and occasional periodic review (to check sites hadn’t stagnated) so should be scalable.