Ember CLI Addon Docs: Shared Documentation for the Ember Ecosystem
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!
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!
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:
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:
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!
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+
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.
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
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.