On our road to modern Ember here at Addepar, we’ve been hard at work developing a new component library to replace a lot of our older components, such as the now deprecated Ember Widgets library. As anyone who has built a shared toolset of components will know, one of the more tedious tasks faced by a library developer is documentation — users of the new components need to be able to reference the APIs to know how to use them, and having a single source of truth for your docs is invaluable to developer productivity, but setting up docs in the first place is a lot of hard work!

For Ember, part of the problem is that there is no standard documentation solution as of yet. The core Ember and Ember-CLI API docs use YUIDoc to generate docs automatically, but it is an aging library which doesn’t have much support for modern javascript features. JSDoc is also falling behind the times lately, and newer doc tools like ESDoc and Documentation.js are still too experimental for widespread use. Moreover, none of these tools targets Ember — they are meant for generic Javascript usage and don’t highlight things that Ember devs need to know, like what arguments a component receives, what actions it sends, or what values it yields.

Worse yet, none of these tools has support for live examples and demos. To get those, most addon authors resort to building an Ember app, usually using the test application (or Dummy app) included with the addon. Building an app takes time and effort, and in the end this means that very few addons in the ecosystem are fully documented with good examples and well described APIs.

When we started to set up our documentation we ran into all of these issues, and we began wondering where the shared solution was for Ember documentation. As often happens in the Ember community, it turned out others had been wondering this as well! We joined forces with Sam Selikoff, Dan Freeman, and the Ember Learning team to work on ember-cli-addon-docs, a project whose goal is to provide a simple and unified way to document all Ember addons. The results have been amazing so far, and with v1.0.0 approaching quickly it supports:

Markdown-based templates

Snippets and live demos

Unified styles and components

Versioned documentation

Automated deployments

Full text search of the guides and the API docs

Generated API docs with a plugin system for multiple backing generators (Currently supports YUIDoc and ESDoc)

API docs for Ember concepts, like components

All of this gets wrapped up in your dummy application with minimal setup, so in the end, it’s still Just an Ember App — you can customize the look and feel and functionality however you choose!