Elm Example Publisher

Today I would like to show you a tool I’ve been working on and using for a long time, but have finally taken some time to polishing enough to make it more widely used.

The Elm Packages Website is very good for API documentation, but doesn’t provide other forms of documentation. One kind, namely didactical examples, are often needed by some packages. For example graphics packages often work a bit like this:

DodWFQ9mQkVyWoKFa0ZIu12PYrPo3P2T0taaK-lgJCo

Or in other words many packages work by giving you the pieces, but it’s up to you to assemble something useful out of them. Authors of these packages typically solve this problem by providing a directory of example programs, so you can learn some common patterns and see how the pieces fit together in something that is a bit realistic, but avoids much of the incidental complexity of a real app (so something like a step 1.5 in the above meme). However, a directory in GitHub makes it a bit hard to see the output of the examples without running them. Also as the number of examples grow, it can become hard to identify quickly which examples may be relevant to ones use case.

Elm-visualization has been tackling these problems for a few years now. The tool I’ve been using for this is called elm-example-publisher. It takes a directory of sample programs and turns it into an attractive website.

This website is written in Elm and can have some interesting features:

  • Examples run on the page as well as showing their source.
  • The index shows each example with a screenshot, allowing a user to visually identify examples that seem relevant.
  • Examples have an Edit on Ellie link to quickly play with the examples (in the demo website some of these are slightly broken, but that is due to not being built from a release tag)

There are some interesting technical features as well:

  • The website is completely static (and apart from the examples themselves) runs even without JS
  • It works great with Netlify for building and hosting in the Cloud
  • The build system is flexible enough to support other documentations styles like categories, tags, or even non-visual examples

If this sounds interesting, please check out the README and give the tool a shot.

42 Likes

no swear words please

I think this is great! When learning some of elm’s larger packages (terezka/ line-charts, ianmackenzie/ elm-3d-scene, mdgriffith/ elm-animator, and your elm-visualization of course!) I’ve found the examples were the most helpful resource by far. And while those post examples in their own ways, I expect tools like this to lower the friction towards nice examples will be great for the ecosystem.

1 Like

Interesting! I have a very similar scenario for my elm-ui-patterns site, but it never occurred to me that the implementation could be turned into something reusable.

1 Like

If you want to simplify the Ellie code, there’s a little-known feature where you can prefill a new Ellie without having to save

https://ellie-app.com/a/example/v1?title=hello%20world&elmcode=hello&htmlcode=world&packages=elm%2Fbrowser%401.0.2&elmversion=0.19.0

We added the feature for this exact purpose!

(Small thing - the percent decoder doesn’t handle + correctly so you have to use %20 for spaces)

5 Likes

Oh that’s cool, I was looking for something like that but couldn’t find anything, so I decided to reverse engineer how Ellie works. There is a nice GraphQL api behind it which was easy enough to repurpose for this.

The only thing I would slightly worry about for longer examples is URL length limits…

This is such a great idea, I hope it catches on.

One small suggestion - if there’s a way to list dependencies for each example, that would be great! I know they’re all listed in the example directory’s elm.json, but even so it’s not evident what modules they expose from their names, especially when there are many packages in the list.

For example, it took me ages to figure out where Html.Events.Extra.Mouse was coming from when I was trying to use one of the elm-visualization examples.

2 Likes

That would be really cool. I think there could be more done for the example source code in general. I often find I would like to check the docs of some function when reading the example code, but I have to search in a separate window.

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.