ember-learn / ember-cli-addon-docs

Easy, beautiful docs for your OSS Ember addons

ember-cli-addon-docs

---

Compatibility

• Ember.js v4.4 or above
• Ember CLI v4.4 or above
• Node.js v18 or above

The original maintainers of AddonDocs have moved on, but this addon is still very much actively maintained and is still being used by many addons. We are currently working on embroider and fastboot support, and would love help, if anyone would like to help out!

If you run into parts of the guides that are confusing or out-of-date, check the issues/PRs, or hop into the #ec-addon-docs channel in Discord.

---

Easy documentation for Ember addons.

View the docs here.

Feature requests

Please open an issue and add a 👍 emoji reaction. We will use the number of reactions as votes to indicate community interest, which will in turn help us prioritize feature development.

You can view the most-upvoted feature requests with this link.

Getting help

Please open an issue or join the Ember community on Discord

About

Created and maintained by Dan Freeman, Chris Garrett, and Sam Selikoff. Thanks to all of our contributors!

License

This project is licensed under the MIT License.

ember-cli-addon-docs's Issues

Install ember-cli-sass

Should host app need to install? Its a dependency...

Build error: Cannot find module 'ember-source'

In 1b87fa7 I added this line to index.js:

app.import(path.join(require.resolve('ember-source'), '../dist', 'ember-template-compiler.js'));

This is used for the DocsDemo component. There's a live-example version that allows users to recompile the template on the client, so we ship the template compiler as part of the dist build.

The latest build on Travis is having some issues. The default scenario works but every other one fails. Here's an example. The failure is

Cannot find module 'ember-source'

which is coming from the require.resolve('ember-source') line above.

Could anybody help me figure this out?

Update `demoURL` on installation

Ember Observer looks for a demoURL key under ember-addon in an addon's package.json to optionally add a link to that addon's demo/docs site. We could set this for the host in our default blueprint if there isn't one already present.

API viewer

Right now this is a route within the dummy app, but that would mean everyone would need to recreate it in their own dummy app.

I think it should either be a component or even possibly an engine. Let's probably start with a component.

But first let's get it working how we like it within the dummy app, and then extract it out.

Limit the number of matches we show per search result

This is particularly painful with short search terms, but it could easily happen with longer ones if they appear a lot in a single document.

Add info about router-scroll configuration

Quickstart install issue

ember install ember-learn/ember-cli-addon-docs

Yarn: Installed ember-learn/ember-cli-addon-docs
WARNING: Could not figure out blueprint name from: "ember-learn/ember-cli-addon-docs". Please install the addon blueprint via "ember generate <addon-name>" if necessary.
Installed addon package.

ember s

WARNING: ember-cli-addon-docs needs plugins to generate API documentation. You can install the default with `ember install ember-cli-addon-docs-yuidoc`
Livereload server on http://localhost:7020
Build Error (Babel)

dummy/components/esdoc-component.js: Unexpected token (28:2)

  26 |     The count
  27 |   */
> 28 |   @argument
     |   ^
  29 |   @type('number')
  30 |   count = 0;
  31 |


Stack Trace and Error Report: /var/folders/d2/_qddrkd50vn4wx7vvfxhhtvc0000gn/T/error.dump.57f8d857050249531c059798577b0bb7.log
cleaning up...

ember-cli: 2.16.2
node: 6.11.4
os: darwin x64

Copy button not found

Missed check in?

Installing

Wanted to start moving Mirage over to use this (and to help flesh out docs), ran into this:

Docs snippet, max width and scroll

Set up (& document) auto npm publish

loadSearchIndex throws error in fastboot

App is being served by FastBoot
There was an error running your app in fastboot. More info about the error:
 TypeError: Cannot read property 'get' of undefined
    at Class.loadSearchIndex (ember-cli-addon-docs/services/docs-search.js:320:1)

https://github.com/ember-learn/ember-cli-addon-docs/blob/master/addon/services/docs-search.js#L77

https://github.com/ember-learn/ember-cli-addon-docs/blob/master/addon/components/docs-viewer/x-search/component.js#L24

What do you think of moving this to didInsertElement? I can PR it if it's the right approach.

Images don't resolve correctly in Github hosted documents

Not 100% sure, but I believe Github hosted ember app should change rootURL accordingly here: https://github.com/ember-learn/ember-cli-addon-docs/blob/master/tests/dummy/config/environment.js#L8

Figure out & document how to support older versions of sites

For example I will use this to rewrite Mirage's docs site. Want to port over the old versions and probably put them in a static place, public? Have to think about this.

yuidoc seemingly breaks demo app

I just wanted to start simple and consume the hero/navbar components in my existing app as I added more functionality from this addon. However, apparently this addon immediately jumps to doing a lot of additional work that causes my dummy app to literally just fail to build once this addon gets installed. How can I avoid this?

Example Error:

Build Error (DocsGenerator)

Cannot read property 'methods' of undefined

Add classes to markdown-transformed tags

It's possible to render ember components inside of markdown templates, which is amazing, because it lets you write prose in markdown while still having demos and not having to move everything over to hbs.

But, we have a .docs-md class that styles tags (.docs-md h1, .docs-md a and so on), which leaks into component demos.

We need our markdowner to add .docs-md-h1 class to all h1's it transforms, .docs-md-p to all paragraphs and so on. I'm sure it's an option in whatever markdown transformer we're using.

Can someone do this? ❤️

this.parent.name is not a function

When I pull this repo into my project and start it up, the first thing I get is this.parent.name is not a function. After inspection, I found the parent.name is returning a string. Also, there's no such method as findAddonByName.

I can get around this by modifying the index.js and ignoring that logic for now, but any ideas as to why I'm seeing this?

List our supported Ember version(s)

Does ember-cli-addon-docs support Ember 1.11 and 1.13? I am trying to use this addon for my open source and I got the error:

Using a version of ember-cli-shims prior to 0.1.0 will cause errors while loading Ember Data 2.3.0-
beta.3+. Please update ember-cli-shims from 0.0.6 to 0.1.0.
An error occurred in the constructor for ember-data at 
/home/travis/build/Addepar/ember-table/node_modules/ember-cli-addon-docs/node_modules/ember-data

An error occurred in the constructor for ember-cli-addon-docs at 
/home/travis/build/Addepar/ember-table/node_modules/ember-cli-addon-docs

Build failure with scoped package addon

Hi, I was trying out this addon in one of our internal addons. Our addon is hosted privately in an organization scope on npmjs and the name in package.json is in the form @organization/package-name.

When running ember serve I got the following error message:

› ember s
Livereload server on http://localhost:7020
The Broccoli Plugin: [BroccoliMergeTrees] failed with:
Error: ENOENT: no such file or directory, open '/Users/xxx/work/package-name/tmp/docs_generator-output_path-Krhjlfrc.tmp/docs/project-versions/@organization/package-name-0.5.1+344612b9.json'
  at Object.fs.openSync (fs.js:646:18)
  at Object.fs.writeFileSync (fs.js:1291:33)
  at Object.writeFileSync (/Users/xxx/work/package-name/node_modules/ember-cli-addon-docs/node_modules/jsonfile/index.js:117:13)
  at DocsGenerator.build (/Users/xxx/work/package-name/node_modules/ember-cli-addon-docs/lib/broccoli/docs-generator.js:39:8)

And when checking the build output folder docs_generator-output_path-Krhjlfrc.tmp/docs I could see that the folders project-versions and projects were empty.

When temporary removing the scope from the package name in package.json the project builds as expected.

Should the folder name maybe be taken from the name specified in index.js instead?

Design versioned API docs feature

Missing files when installing from NPM

If you install the NPM package for [email protected] you end up missing a bunch of files that you need for the docs to work correctly.

For example, the contents of the app tree are:

app
├── templates
└── transitions.js

1 directory, 1 file

The template files for rendering the docs/api/item route are missing.

There's also some missing addon files, for example:

addon/routes
└── docs.js

0 directories, 1 file

even though the commit tagged as v0.2.0 has more than that in the addon/routes directory.

API reference rendering bug

If you visit /docs/api you'll see I have some of the text form the components. Right now the data is rendered using double curlies. When I try to render as HTML using triple curlies {{{ }}}, the rendering isn't cleaned up as I navigate around the app.

After we figure this out I can go back to designing out these pages a bit more and making some useful components for people to use.

Add < and > arrows to the bottom of each page of the docs-viewer

Allow caller to specify language when rendering code-snippet from handlebars template

I have a HBS template and I want to show a diff, which I would normally use ```diff for (github fences). Here's my template:

{{#docs-snippet name="your-snippet-name"}}
  model() {
-   return this.get('store').findAll('post');
+   return this.get('storefront').findAll('post');
  }

  model() {
-   return this.get('store').findRecord('post', 1);
+   return this.get('storefront').findRecord('post', 1);
  }
{{/docs-snippet}}

This works but I want to be able to say, "this snippet is actually a diff snippet (or a ruby snippet, etc.)". Perhaps a lang="diff" option to the {{docs-snippet}} component.

Support {{docs-logo logo="ember-data"}}

I'm not sure how the svg was generated for ember and ember-cli, but it'd be great to have one for

Versioned guides

Remove version/sha postfix from Class URLs

e.g.

http://localhost:4200/docs/api/DocsHero-0.1.0+daa3b6a3

should just be

http://localhost:4200/docs/api/DocsHero

Markdown files are not capturing Snippets

For some reason the Snippets plugin is only finding snippet-templates in the .hbs files. You would think after a .md file is transformed into a .hbs file it would work, but apparently something is up.

Investigation in progress... 🔍

Suggestion: Optionally hide private classes/fields

I like to be pretty thorough with JSDoc, even with internal classes and methods. Right now, anything that has a commented is shown in the docs, whether or not it's actually public. It would be really cool to be able to hide private stuff, or have something in the UI that allows you to optionally view private stuff as well as public.

Right now the solution is to remove the private documentation so that to doesn't leak into the site, but I'd rather not have to do that. That information can be useful to myself later on, when coming back to some work I did a long time ago.

If this is a feature you're interested in, I'd love to help work on the solution!

Add showCopy option to docs-snippet

Default to true

Error: Compile Error: docs-snippet is not a helper

app/pods/components/docs-snippet/component.js assumes everyone is using pod 😦

Should include `ember-ajax` as a dependency

My addon removed the default ember-ajax dependency. ember-cli-addon-docs requires it but just assumes it'll be present. ember-ajax should be moved to the dependencies of the addon (or better yet, removed altogether)

`docs-demo` fails to compile template with certain actions on elements

I'm trying to re-write my documentation for ember-steps using this addon and am running into trouble with the docs-demo component. For example, this snippet fails to compile in a Markdown file, despite being valid Handlebars

{{#docs-demo as |demo|}}
  {{#demo.example name='cookbook-tabs.hbs'}}
    {{#step-manager as |w|}}
      <button {{action w.transition-to 'first'}}>
        First Tab
      </button>
      <button>
        Second Tab
      </button>

      <hr>

      {{#w.step name='first'}}
        This content is on the first tab
      {{/w.step}}

      {{#w.step name='second'}}
        This content is on the second tab
      {{/w.step}}
    {{/step-manager}}
  {{/demo.example}}

  {{demo.snippet 'cookbook-tabs.hbs'}}
{{/docs-demo}}

It chokes on this part:

<button {{action w.transition-to 'first'}}>
  First
</button>

with the following error:

Closing tag button (on line 7) without an open tag.

Some different variations of the {{action}} also fail, such as this:

<button {{action w.transition-to 'first'}}>
  First
</button>

This one passes compilation, but doesn't actually do what I want it to

<button {{action w.transition-to}}>
  First
</button>

Don't run ember deploy on PR CI builds

Could not find module `dummy/snippets`

Hey guys,

Fantastic work so far! I'm currently beta testing your addon and when I tried to use the docs-snippet component, I'm getting this error:

Could not find module `dummy/snippets` imported from `ember-cli-addon-docs/components/docs-snippet/component

My template has something like this:

{{#docs-snippet name="your-snippet-name"}}
  {{my-component}}Hello World!{{/my-component}}
{{/docs-snippet}}

Any ideas? Perhaps I missed a config?

Add `docs-md` wrapper class to markdown-generated HTML

We need to PR ember-cli-markdown-templates to give us an option for wrapping Markdownifies template files with a class, otherwise folks won't be able to easily style those pages.

We want to do this so Markdown templates can stay as pure template.md files.

ryedeer/ember-cli-markdown-templates#1

Sidebar Navigation Index Strategy

There are a number of different strategies we have been discussing for setting up the index in the sidebar of ec-addon-docs, and this issue seeks to enumerate them so we can get some consensus on the best path moving forward.

Modules vs Types

Fundamentally, there are two main modes of thinking about the index - we can either show a listing based on the module structure of the addon, or we can show a listing based on the types of the things being documented. For example:

Modules

/components
  {{foo-component}}

/components/utils
  [c] BaseComponentClass
  [f] componentHelperFunc()
  [f] otherFunc()
  [v] STATIC_VALUE

/models
  [c] FooModel

/utils
  [f] helperFunc()
  [v] CONSTANT_VALUE  

vs

Components
  {{foo-component}}

Classes
  BaseComponentClass
  FooModel

Functions
  componentHelperFunc()
  helperFunc()
  otherFunc()

Variables
  CONSTANT_VALUE
  STATIC_VALUE

Modules are the new paradigm in JS - most old doc tools like YUIDoc and JSDoc didn't have support for them for the longest time, and still don't have full support. These tools were much more class oriented, and employed the Types strategy.

Both of these strategies are suboptimal - Modules focuses too much on the layout in the file system and doesn't easily allow developers to see the bigger picture, a bad file system layout can make the docs very hard to reason about. However, Modules do allow for related functionality to be grouped together, something which can get very confusing in the Types system (note in the above example, functions from /components/utils end up split apart due to alphabetical ordering in the Types layout).

Strategies

For the following strategies we will use a subset of the addon structure of Liquid Fire. This subset contains some files which would likely be considered private and not part of LF's exteranl API, but they are included for two main reasons

1. They are representative of a large addons potential API space, and diversity will let us see the complex edge/corner cases here to make a decision that isn't a massive footgun
2. Developers actually working on LF would likely benefit from having access to the private docs - this is true for most large addons. While not a primary priority, it would be ideal to have a system that is "toggle-able" and allows developers to quickly see documentation for private APIs if they want to contribute to the addon/library.

The structure has also been modified slightly to bring out certain edge cases (like pod modules, for instance)

/components
  /liquid-bind
    /component.js
      LiquidBind
  /liquid-if
    /component.js
      LiquidIf
  /liquid-outlet.js
    /component.js
      LiquidOutlet
  /liquid-unless.js
    /component.js
      LiquidUnless

/helpers
  /lf-lock-model.js
    lfLockModel()
  /lf-or.js
    lfOr()

/mixins
  /pausable.js
    Pausable

/services
  /liquid-fire-transitions.js
    TransitionMap

/transitions
  /fade.js
    fade()
  /default.js
    default()
  /move-over.js
    moveOver()
  /explode.js
    explode()

/animate.js
  animate()
  stop()
  isAnimating()
  timeSpent()
  timeRemaining()
  finish()

/promise.js
  Promise

/mutation-observer.js
  MutatationObserver

Modules With Hosting

As we noted before, modules can be suboptimal because it depends heavily on the file structure being decent. However, Ember has an advantage here because the file system is generally decent - it's dominated by very well known conventions throughout the Ember ecosystem. The Modules With Hoisting approach would use this to our advantage, organizing mostly around the module system, but "hoisting" based on a few very simple heuristics:

1. If a file is a component or helper pod, show it as if it were the parent module
2. If an export is a default export, show it as if it belongs to the parent module

These rules are additive, so a typical pod component would be hoisted by two levels for instance. This is the output for this strategy:

/
  Promise
  MutationObserver

/components
  LiquidBind
  LiquidIf
  LiquidOutlet
  LiquidUnless

/helpers
  lfLockModel()
  lfOr()

/mixins
  Pausable

/services
  TransitionMap

/transitions
  fade()
  default()
  moveOver()
  explode()

/animate
  animate()
  stop()
  isAnimating()
  timeSpent()
  timeRemaining()
  finish()

Resolved Types w/ Modules

For this strategy, we would leverage the fact that Ember has a notion of "globals" via the resolver. We can be sure, based on the structure of an addon, that certain constructs like Components, Services, etc will be essentially in a global namespace and will not have naming collisions. This strategy would follow the resolver directly - anything that isn't a resolved type would be considered one of the primitive types (Class, Function, Variable/Constant). For consistency, these would also be divided by type, but each type would also show module paths (potentially with hoisting as described above):

Components
  LiquidBind
  LiquidIf
  LiquidOutlet
  LiquidUnless

Helpers
  lfLockModel()
  lfOr()

Services
  TransitionMap

Classes
  /
    Promise
    MutationObserver
  /mixins
    Pausable

Functions
  /transitions
    fade()
    default()
    moveOver()
    explode()

  /animate
    animate()
    stop()
    isAnimating()
    timeSpent()
    timeRemaining()
    finish()

Resolved Types+ w/ Modules

This strategy is the same as resolved types, but with additional heuristics for unresolved types that are still generally considered "primitive" types in Ember. The only real example of this use cases would be Mixins, and the heuristic would be to check against class name, route name, and possibly a manual tag users could add.

Components
  LiquidBind
  LiquidIf
  LiquidOutlet
  LiquidUnless

Helpers
  lfLockModel()
  lfOr()

Mixins
  Pausable  

Services
  TransitionMap

Classes
  /
    Promise
    MutationObserver

Functions
  /transitions
    fade()
    default()
    moveOver()
    explode()

  /animate
    animate()
    stop()
    isAnimating()
    timeSpent()
    timeRemaining()
    finish()

Add links to headings

from markdown content

Does this support apps as well?

Probably a very silly question but would we be able to use this addon for documenting our main project/app as well (or is it only intended/suitable for Ember addons)?

Quest issue for MVP

Prioritized features for MVP:

• Versioned API docs
• Versioned guides
• Boilerplates for using these

Document deployment in guides

• Out-of-the-box defaults (gh-pages branch, hash locationType, etc)
• Customizing deploy behavior (hooks in config/addon-docs.js)
• Configuring deployment as part of CI (generating a key pair, setting up GitHub and Travis)

Only change `rootURL` in prod environment

So dev stays in 4200

Update `SearchIndexer` for the new API docs format

This method and the logic that decides to invoke it need to be updated to consume the new documentation structure.

Fastboot build is not working because of fetch

Issue 1

There is fastboot regression introduced in PR #58.

ReferenceError: fetch is not defined  

Possible solution:
Add ember-fetch and use fetch for making requests:

• docs-search service
• application adapter

However there is problem with ember-fetch itself ember-cli/ember-fetch#62

Issue 2

One more issue discovered during fastboot tests:

Adding ?fastboot=false(or basically any query param) to URL throws error because route cannot be found in docs-routes service

ember-cli-addon-docs/addon/services/docs-routes.js

Lines 42 to 45 in fb16174

	currentURL = currentURL
	.replace("//", "/") // dedup slashes
	.replace(/\/$/, "") // remove trailing slash
	.replace(/#.+$/, ''); // remove # anchor links

This one can be fixed with adding one more replace:

.replace(/\?.+$/, ''); // remove query-params

Add "Edit this page" link to the top of every page

What is this project?

Could someone put in a summary in the readme of the purpose/goals of this project?

Is code-snippet config supposed to be in index.js?

Is the code-snippet config supposed to be in index.js, since we want it to affect the host app?

https://github.com/ember-learn/ember-cli-addon-docs/blob/master/ember-cli-build.js#L9-L13

I tried a bit but couldn't figure it out.

Adapter with `/docs` prefix should only apply to addon-docs resources

like class, project-version, project etc.

Make live examples opt-outable

The template compiler adds a non-negligible amount of weight to the final app payload (~100KB gzipped), and a code editor like ember-ace or ivy-codemirror adds a similar amount again.

For a lot of authors, it'll totally be worth that cost for the benefits the live code examples bring, but for addons where they don't add much, being able to avoid that 200KB download/parse hit would be nice.

DocsDemo component

I basically have this written just need to port.