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