Wombat Security Technologies is open sourcing an ember addon for providing better documentation for your ember components. Check it out here.
A note about documentation
An often missed detail of successful documentation is maintaining it to stay current with your implementation. To this end developers have invented a great many inline documentation tools and utilities to allow them to update documentation in the same places that they change their code. However, Ember’s component implementations require an additional level of explanation outside the component itself code for how to invoke and configure an example component. This layer is often documented as an ‘example snippet’ of HBS code that is completely static and separate from the component’s invocation on the page.
The reason for this is because ember’s template compiler doesn’t leave any scraps of pre-compiled HBS source laying around for reuse. This optimization’s purpose for template compilation makes total sense but leaves us scratching our heads about how to show the uncompiled source for our components in an example snippet without unneeded duplication. What we really want is to just write our example component once, and have that example serve as the same source for our HBS snippet.
Finally there is a solution to this documentation problem: ember-component-showcase!
Inspired by ember-freestyle’s live style guide addon, but implemented as a radically simpler and less opinionated documentation component. We use this component internally at Wombat to document our own style guide components, and now we are open sourcing this utility to the community. The default styling on the showcase samples are intentionally minimalistic so it will work with most style frameworks or your own internal CSS/SCSS.
The easiest way to use the component is to simply wrap the content you want make an example for in the
component-showcase component. This will create a ‘showcase’ for your component and will automatically parse out the HBS markup that was used to invoke it.
By providing a ‘title’ string and a ‘description’ string to the component, you can qualify the showcase example and provide context for how to use it.
These showcase samples can be linked to by using the ‘link’ anchor in the top right. Using this feature requires importing the
anchor-scroll mixin into your application controller.
However many components can be more complicated than this simple usage covers, for this we have extended customization options available as well.
If you have a more complicated component that involves properties configured via a route or controller you may want a better way to exhibit those relationships in your showcase as well. To that end ember-component-showcase has an advanced block syntax option that allows you to expand your control of the presentation of your sample component.
We can take this to the next level by even including extra source tabs for additional documentation outside of the HBS markup. Simply pass extra tabs through the array helper into the
You can also enable the raw HTML compiled source by passing
hideHTML=false to the
We still have a few things that need to be resolved in this addon before everything is totally in working order as I would expect. As is usually the case with new addons we need to beef up our testing to make sure we are covering more integration scenarios. This is a little trickier than it would usually be when testing a component because of the nature of our component relying on ember’s template compiler.
We also have to implement a template caching strategy. Currently there is a warning when using this addon that informs you that template caching is currently disabled. This is due to the hooks into the compiler being implemented without any clear way to tell ember when a compiled file should be invalidated. This doesn’t have a huge impact in terms of performance for most ember applications, but obviously is an optimization worth landing in the near future.
Finally we have big plans for expanding support for using inline documentation tools with this component. We originally prototyped this to work with Yuidoc using a manual task runner to generate a documentation collection, which could then be linked to a specific showcase via a namespace. Ultimately this approach is tremendously useful, but it would be even more so if we could leverage tools like ember-cli-yuidoc.