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:
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.
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.
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.
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.
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…
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.
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.
