Ember CLI Addon Docs: Shared Documentation for the Ember Ecosystem

7 min readMar 7, 2018

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!

Installation

Just like any other Ember addon, you can add ember-cli-addon-docs to your project using the ember install command:

ember install ember-cli-addon-docs

This will add a deploy config for deploying your docs to Github pages, and also add the default YUIDoc docs generator. Follow the rest of the quickstart guide to get your docs up and running in no time.

Writing Your Docs

Documentation pages are written using Markdown, which gets compiled to Handlebars templates to make writing documentation super easy. Just add markdown files instead of templates for your routes and they’ll be compiled without any additional configuration:

# Installation

To install My Addon, run...

Using components in the markdown files should Just Work, as should helpers and other arbitrary HTML:

## My Component demo

Here's a demo of it working:

{{my-component-demo-1}}

Check out the patterns section of the documentation to see the recommended best practices for organizing your docs.

Demos, Snippets, and More

Ember-cli-addon-docs also comes with a bunch of components to help you write examples, including a nifty demo component:

The component uses contextual components to allow you to define your example and render it at the same time, so no need to duplicate code from one place to the other. The addon also comes with built in snippet support using ember-code-snippet, so you can add arbitrary snippets if you want:

It also has a live demo component that allows you to create demos users can change on the fly, allowing them to experiment and test out your code in the documentation:

These components give you an amazing toolset for quickly and easily scaffolding up rich examples for your library, and make communicating your features easier than ever!

API Documentation

The ability to use markdown and a toolset of components makes creating a full-fledged addon site easier than ever. However, they still require a fair amount of effort to maintain, and it’s hard to add detailed descriptions of each component, class, function, and variable by hand. Automated API documentation comes in handy here, and ember-cli-addon-docs provides a modern approach to making the best generated docs for Ember users out there.

Made For ES2018+

The API docs are modeled to reflect modern Javascript paradigms. Modules are first class citizens, and the existing generators automatically figure out module structure so you don’t need to manually tag them (even with YUIDoc)!

Modules can document Classes, Functions, and Variables, just like native javascript. Classes can document their Fields, Methods, and Accessors (getters/setters), and all of these things have support for arbitrary tags and decorators, which can be parsed by ESDoc and other modern generators.

If you want to mix and match modern ES class syntax with the older Ember object model, you can run multiple doc generators side-by-side, meaning you can incrementally convert your project from the old standards to the new standards without a gap in documentation.

Made For Ember

The API docs are crafted specifically to match the structure of Ember applications. The navigation panel reflects this, displaying a list of the “global” resolved types such as Components, Services, Controllers, Helpers, Routes, and more. Components also have Arguments and Yields:

Using tags or decorators, you can document what your users should pass into a component and what they can expect when using its block form. This is much more valuable information to most users than the Methods, Fields, and Accessors of a component, which are, generally speaking, “private” implementation details: unless they extend your component, most users are never going to know about them.

Automated Everything

Ember-cli-addon-docs supports versioned documentation and automated deployments to Github Pages out of the box, with minimal setup required. Older versions of your docs pages are built and stored in a subdirectory in pages, along with a latest and master version by default which allow you to always point people to the current stable and bleeding edge releases. A search index is also automatically generated for your entire site, allowing users to quickly find exactly what they’re looking for.

Features like these prevent you from having to do the hard work to maintain versioning in your docs and keep then easily navigable. The addon is dedicated to automating as much of the process of generating documentation as possible, so you don’t have to!

Towards the Future

Ember-cli-addon-docs is still pre-1.0.0, but it’s evolving quickly and should reach a stable release soon. In the future, we’d like to continue evolving its features and making it even easier to bring documentation to the Ember ecosystem.

When you look at other communities out there to emulate in this realm, the greatest example is probably the Rust Documentation. Every time a Rust package is built and published, its versioned API docs are built and published as well:

That level of simplicity and automation is simply amazing. The entire ecosystem can quickly and easily find the docs for just about any package available, and maintainers have little-to-no setup or maintenance required on their end.

This type of community support is what ember-cli-addon-docs is aiming to achieve in the long run. By standardizing on a shared documentation solution, we can also standardize the way we share and access that documentation and make it easier for every Ember developer to stop worrying about writing docs and just get things done!

Big thanks to Sam Selikoff and Dan Freeman, who started this project and did all of the work on the design, components, markdown compilation, and deployment logic, and to the Ember Learning team for support and inspiration!

If you’re looking for advice in using the library, would like to provide feedback and track progress, or would like to help contribute, feel free to open up an issue on Github or to join us in #ec-addon-docs in the Ember Community Slack.