TLDR

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.

<div class="example">
    {{my-component value="foo"}}
</div>
    
<pre class="source">
     '{{my-component value="foo"}}'
</pre>

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!

{{#component-showcase}}
    {{my-component value="foo"}}
{{/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.

Basic Usage

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.

{{#component-showcase "Simple Showcase" "For simple usage just put your component sample inside the `component-showcase` block." }}
  {{my-component value="foo"}}
{{/component-showcase}}

However many components can be more complicated than this simple usage covers, for this we have extended customization options available as well.

Advanced Usage

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 source sub-component. You can also enable the raw HTML compiled source by passing hideHTML=false to the source sub-component.

{{#component-showcase "Custom Block Showcase" as |s|}}
  {{s.docs "More sophisticated showcases can be composed using the sub-components `docs`, `example` & `source`."}}
  {{s.docs "You can have as many source blocks as you'd like, they *automatically compile* from [markdown](https://daringfireball.net/projects/markdown/syntax) for you."}}
  {{#s.example}}
    {{#power-select options=countries selected=country onchange=(action "foo") as |country|}}
      {{country.name}}
    {{/power-select}}
  {{/s.example}}
  <p>You can even qualify your examples with any other markup you want.</p>
  {{s.source (array (hash title="route.js" language="JavaScript" src="var foo = 'foo'")) hideHTML=false}}
  <p>Or after them!</p>
{{/component-showcase}}

Next steps

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.