Ember-CLI Addons
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
Title |
| |
Title of Series | ||
Number of Parts | 27 | |
Author | ||
License | CC Attribution - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
Identifiers | 10.5446/35711 (DOI) | |
Publisher | ||
Release Date | ||
Language | ||
Producer | ||
Production Year | 2018 |
Content Metadata
Subject Area | |
Genre |
EmberConf 20183 / 27
3
4
6
8
12
13
15
16
18
21
22
23
25
26
00:00
VideoconferencingXML
00:10
Linker (computing)Library (computing)Event horizonFiber bundleMarkup languageModul <Datentyp>Texture mappingFunction (mathematics)WebsiteMereologyVideoconferencingSoftware developerDataflowData miningMultiplication signComputer animation
00:53
Dew pointMultiplication signRevision controlWebsite
01:11
Numeral (linguistics)Common Language InfrastructureLimit (category theory)Asynchronous Transfer ModeNavigation
01:19
Common Language InfrastructurePower (physics)Scale (map)Rule of inferenceQuery languageHamiltonian (quantum mechanics)Source codeHeat transferCross-site scriptingSlide ruleLiquidHypermediaExplosionView (database)Data miningMathematicsMaxima and minimaSlide ruleLiquidBitWebsiteStatisticsConnectivity (graph theory)Concurrency (computer science)Power (physics)Mobile appFluid statics
02:12
Archaeological field surveyAugmented realitySoftware developerWebsiteGoodness of fit
02:39
Common Language InfrastructureCommon Language Infrastructure
02:52
Execution unitFingerprintComputer fileWebsiteMultiplication signInheritance (object-oriented programming)Common Language InfrastructureCoefficient of determinationDampingCodeSoftware developerDot productLattice (order)Lecture/Conference
03:25
CodeCodeDemo (music)Mobile appWebsiteSynchronizationConnectivity (graph theory)Default (computer science)Lecture/Conference
03:40
Maxima and minimaEmailSynchronizationCASE <Informatik>Disk read-and-write headAsynchronous Transfer ModeCuboidDemo (music)CodeSoftware testing
04:03
CodeSoftware testingSoftware testingMobile appWebsiteWritingConnectivity (graph theory)SubsetAtomic numberComputer animation
04:34
CloningSynchronizationWebsiteSoftware testingData structureTouchscreenComputer animation
04:56
CodeSoftware testingSource codeSource codeWebsiteDevolution (biology)Computer animation
05:07
Demo (music)Euclidean vectorObject (grammar)Field (computer science)Price indexHash functionFile viewerCorrelation and dependenceDefault (computer science)Computer clusterKeyboard shortcutString (computer science)GenderComputer iconFormal languageEntire functionSheaf (mathematics)Ocean currentLogicNavigationConnectivity (graph theory)Filter <Stochastik>Source codeRevision controlProjective planeMobile appFocus (optics)Order (biology)Web pageCASE <Informatik>Cuboid
05:44
Revision controlSource codeCodeSoftware testingWeb pageWeb pageCodeRevision controlMultiplication signMobile appPattern languageElectronic program guideFreewareCuboidBuildingProjective planeGroup actionWebsiteSoftware repositoryRobotComputer animation
06:31
Web pageSheaf (mathematics)Data structureSpacetimeAreaFile viewerIdeal (ethics)Right angleSocial classMobile appParsingMultiplication signDifferent (Kate Ryan album)Electronic program guideAuthorizationSubject indexingCodeCommon Language InfrastructureWeb pageMassArithmetic progressionEvent horizonMoment (mathematics)Computer animation
07:23
Linker (computing)Daylight saving timeSquare numberComputer animation
07:29
Computer animation
07:35
Coma BerenicesComputer animationXML
07:46
Block (periodic table)Data typeComputer animation
Transcript: English(auto-generated)
00:20
this is an awesome site. This is the coolest documentation site I've ever seen. Anyways,
00:29
my name is Sam and we're going to be talking about documentation. I make videos for Ember developers on embermap.com if you don't know who I am. I love documentation sites.
00:40
They're great. Look how beautiful they are. They're such an important part of our workflow as developers. We use these things all the time, how they look, how they work is just critical to how productive we can be. When I made Mirage and put together a doc site a few years ago, I looked at what was available at the time and I wanted to
01:01
make something that looked pretty good, had versions, was clear, made it easy for contributors to edit and update, and this is kind of what I ended up with. And some of you kind of squint your eyes and you look at the left-hand nav and the top nav, you can see that they're very similar and that's actually because Ember slide deploy's doc
01:24
site started as a fork of Mirage's. And if you look at power select, you'll see the same thing. So that was pretty cool. You know, folks liked what I came up with and that worked for a bit. Now I was really interested when I saw LiquidFire's doc site
01:40
because Mirage's doc site was made with Jekyll, which is a static site generator from Ruby. But Ed, for LiquidFire, needed more than just a plain static site. He wanted a whole Ember app because for his documentation site to be effective, he needed to demonstrate the components, the Ember components, that came with LiquidFire. And you can see the same thing for Ember concurrency here with
02:04
Alex. And so really, a static site wasn't suitable for these, you wanted a full fledged Ember app. So as I kind of, you know, I like documentation and was looking at all these different sites and taking kind of a survey of the
02:20
community, I asked what any good Ember developer who's been sufficiently brainwashed would ask, which is, what can we share, right? Because we have all this great infrastructure and when we see people doing the same thing over and over again, there's an opportunity there for us to build up to a higher floor. And it turns out there's actually quite a lot we can share. So this has
02:43
kind of led to this project, Ember CLI add-on docs, which I started and which Dan Freeman and Chris Garrett joined along with, and I just want to give you a quick tour of some of the features. So first thing is the shared styles. If you're an add-on developer, you don't want to have to think about this from scratch every time. So if you use add-on docs, you get a nice looking
03:02
site from the beginning. So these two screenshots are from Ember CLI add-on docs documentation site, and add-on docs is an add-on that's documented with add-on docs. Yeah, so that's its inception, it's super meta, so but it's really cool. It's like the dog fooding of a startup kind of thing, you know. So
03:23
anyways, this is what it looks like, so that's pretty cool. We get auto-generated code snippets, which is something else we borrowed from Ed and LiquidFire's docs, because you don't want your documentation code to fall out of sync with the code that's actually running your doc site. We have components that make it easy to have live demos in your app. So this is
03:43
Storefront, which is another another add-on I work with that's documented using add-on docs, and here you can see there's a demo here that's showing you how to load data using Storefront, and this is the actual code that's running in an Ember app, and it's using Storefront's APIs, and it shows you the code that's powering that demo, and that's all right there for you. So
04:02
having that in the add-on gives you a really great testing story, because the Ember app that you use for your documentation is actually the dummy app that comes with every add-on. So if you've never written an add-on before, add-ons come with a dummy app, which is a full-fledged Ember app, but it ends up being a perfectly suitable place to put your documentation site,
04:21
because it's already wired up with all the dependencies and all the components and stuff that you're defining, and so if you write your documentation site using the dummy app from your add-on, you can write acceptance tests against it. So looking at this demo, I can test, I can explain how a Storefront API works. I can write a test against this and make
04:41
sure that actually when you click the thing, the right data is loaded, and the right stuff shows up on the screen, and that way not only am I making sure my APIs work, but my documentation site is also tested, so my docs will never fall out of sync with my actual add-on. So that's pretty awesome. That was another trick from Ed, by the way. He basically comes up with all the
05:01
ideas. We also auto-generate API reference from your source code, so this is add-on docs current site, and you see add-on docs ships with a lot of components. All these pages, the entire nav section under API reference is auto-generated from either YUI doc or ES doc comments in your source code,
05:20
and these go beyond just the plain comments. These are actually, we do some extra logic to make it more suitable for Ember add-ons, because this whole project is laser focused on the add-on use case, so you see here when I click demo, you can actually see the contextual components that demo yields, and we're gonna add some more filters and all this stuff to clean
05:41
this up even more, but that's kind of the idea. Now you get version docs for free, so the pattern with GitHub is to use the, we deploy to GitHub pages, and typically when you do that, you blow away the old GitHub pages repo, and so you just smash master each time and you just get one version, but
06:02
we have some code that manages it so that every time you tag a release and publish it, it builds that dummy app and it puts it in a subdirectory, and so every time you tag your project and build it and deploy it, you'll get a new version of your documentation site, so basically every add-on we'll get should, using this, we'll get version guides for free out of the box. That's pretty cool.
06:28
And then finally, one really cool thing we can do is implement search for you, and that's because all of your docs are in the code base, they're all in master, so the dummy app lives in master alongside your code, and all the comments on your classes are there as well, so we can scrape that, parse it,
06:44
and build an index and ship that with your Ember app so that we can just give you search for free, and this will search over all your guides pages and your API reference docs. So the goal for this add-on is to be a no-brainer for every add-on author to use. There's a lot of different features, and you
07:01
know, sometimes you might want to use all of them, sometimes you might want to just install it and use a few pieces. Right now, there's, you know, it's still work in progress, but eventually the goal is that you can just install it and use whatever piece you want, so if you're excited about this, then I'd encourage you to check out Ember CLI add-on docs, and thank you so much for your time.