ember-learn / ember-api-docs Goto Github PK

Right now, if you visit https://ember-api-docs.herokuapp.com, you get redirected to the earliest version available, which is currently 1.0.0.

We want to get the last result here, instead of the first result: https://github.com/fivetanley/ember-api-docs/blob/dc6339c52490c4dc0134ec629315b33696c61318/app/routes/project.js#L9

In addition, the dropdown should display in descending order. Meaning that 2.0 should appear in the list before 1.9. That's located in this controller.

To reproduce, click on Ember.ApplicationInstance, Ember.Controller, or Ember.CoreObject

In issue #11 we have the user the ability to toggle off/on display of private classes. The plan currently is to default the public api site to have private off, and possibly hide the toggle. At the same time we want to have an interals site where everything is on by default and toggle-able.

On the old /api pages we have the ability to click an edit button that takes the visitor straight to the corresponding Github page. It would be good to add that functionality back in.

However, we'll need to decide how we want that link to work:

1. We could have it only show up on the latest api docs (indicating that only those docs are editable, as core is unlikely to release a new point release of an old version just to update docs). This doesn't encourage as much participation in editing docs but might be less confusing.

2. We could have it show on all pages, but when clicked send the visitor to the latest version of the page they are on. This does encourage participation, but may be confusing as docs may have been updated since the version of the docs they are viewing (i.e. if they are viewing 2.4 docs and click a link that now takes them to a page discussing Glimmer components as well)

I would probably vote for 1 despite it potentially reducing the amount of api docs editing that we get.

It doesn't currently show up in the header but should

https://github.com/ember-learn/ember-api-docs/pull/117/files#diff-4fe440ae4dbaca7ea3e433eedb54fe76

So far this test fails on Travis most likely because either:

• The screen is too small so the CSS media query to make article overflow:auto is not active
• The screen is too big and therefore all the content fits and scrollTop(1000) has no effect

use ember-cli-eslint to ensure conventions.

Whatever core uses should be fine.

This type of info would be useful to see, we might want to pretty it up while we're at it though ...

We need to steal the favicon.ico from emberjs.com or guides.emberjs.com and stick it in the public folder.

When an error occurs in the application, we should display a "Whoops! Something went wrong." or similar page

As seen here, there is a sidebar on the existing api docs that doesn't exist in the new system

Example in current api docs:

Example in app:

Modules show a link to the parent module (usually ember)

To do this, we would need to change the documents generated by https://github.com/fivetanley/ember-jsonapi-docs.

ideally, each project-version document would not have a classes relationship anymore, but private-classes and public-classes.

I can handle this one.

Currently when viewing the api docs for Ember.Router, methods are properly noted as public or private (http://emberjs.com/api/classes/Ember.Router.html).

With our current setup, when viewing the same class (http://localhost:4200/ember/2.4.3/classes/Ember.Router) the methods list doesn't show visibility information. Looks like this is already a property on the method class (access) so it mainly needs to be displayed ...

Currently using 0.6

Current API doc hides submodules section when no submodules exist. New app shows them. Also, new app shows 3 distinct sections (submodules, namespaces, and class), while the current app combines namespaces and classes. While this is probably ok, we should still hide the sections where details don't exist.

Current app:

New app:

When you scroll down a longer item, and then switch to another item that requires scrolling the new route loads partially scrolled down-screen. We should reset scroll to top on route change.

getting the following on startup:

On the old api docs, you can click a method name on the index page and jump to the appropriate method description even if it's not the top-most result. As an example, visit http://emberjs.com/api/classes/Ember.Router.html and click didTransition on the Index tab.

On the corresponding page in the new app (http://localhost:4200/ember/2.4.3/classes/Ember.Router) clicking didTransition opens the page but doesn't shift down the page.

If we have 2.4.1 and 2.4.2, it should show up as 2.4 on the dropdown and show the 2.4.2 documentation. 2.4.1 and 2.4.2 would then not show up in the dropdown on the sidebar.

Workaround: In applications tab of Chrome, clear the IndexedDb.

For example: https://guides.emberjs.com/v2.4.0/

Starts off closed:

When clicked, opens:

On the guides site, there's a neat little animation that I'm guessing is done by using a CSS transition.

This would be a great component! If you can't find something that works off the shelf (that also works in fastboot), unit tests would be great. It would also be great if we could make this accessible (cc @Robdel12)

When viewing classes on the current API system, displaying "private" methods will also display all inherited private methods for a given class (using http://emberjs.com/api/classes/Ember.Router.html as an example, _lazyInjections shows in the methods list even though it is defined in the Ember.Object class).

In our new data setup, that method won't ever be shown as it's not a public or private method in Ember.Router. I believe this is the appropriate way to handle it, but thought it would be worth mention here (and possibly bringing up with the core team), as any changes to the way API docs are handled tends to also lead to raised voices about missing documentation 😄

Noticed that too much bandwidth was getting utilized by the app when I was inspecting network activity by communicating a lot with cloudant.
By the time I finishing writing down this issue the page had download about 275MB+ content from cloudant.

Layout should be limited to a maximum width

We won't hit this for Emberconf, so let's just remove it for now: https://dl.dropboxusercontent.com/s/1dji9k0mx4i7wvr/2016-03-27%20at%207.39%20PM.png

I think this is in application.hbs

We may need to work through what we're wanting to do here, but it would be nice to replace the api build setup in the emberjs/website repo

To allow people to focus in on only certain items they want to see ...

You can see this problem when viewing the Ember.Component class (https://ember-api-docs.herokuapp.com/ember/2.6.0/classes/Ember.Component)

Currently mixins and parents aren’t currently being handled by Stanley’s setup here: https://github.com/ember-learn/ember-jsonapi-docs The working setup that currently generates what we're after is here (https://github.com/emberjs/website/blob/master/lib/api_docs.rb), so we'll need to work through things and port the logic over to our node setup.

In the current API docs, when viewing a method there is also an option to view the corresponding code on Github (http://emberjs.com/api/classes/Ember.Router.html#method_didTransition). It would be ideal to be able to offer that with this new app as well ...

For example, when you navigate to https://ember-api-docs.herokuapp.com/lol1234, we should display a "Not found" page of some kind

Currently the filter checkboxes are only toggling items in the index. They should also toggle details.

in the left nav of the current api docs, modules are shown before namespaces. In the new api docs, they are shown after. Was there a reason for this? It may cause some confusion for those used to it they other way. (for example there's an ember in both, so one might click on ember module, thinking it was a namespace.)

New app:

Original:

In the old api viewer, we had this section across the top to allow folks to quickly focus on one area ...

On the api docs page now, we have something on the left hand page where you can switch between projects

We could use something like that!

The link markup would look something like

{{#link-to 'project' 'ember'}}Ember{{/link-to}}
{{#link-to 'project' 'ember-data'}}Ember Data{{/link-to}}

It would be nice if it also had the block-ish look like the current api documentation has where the header has a different background, and the links are in a different box beneath the header, with a box surrounding all of it with a border. tl;dr make it look like the current implementation on emberjs.com/api

right now they don't show anything

Step 1: Make sure the "Show Private / Deprecated" Checkbox is unchecked at the bottom of the sidebar
Step 2: Open module, like ember-metal

Notice private classes, such as Descriptor are shown

References to namespaces that don't exist and other data issues break the app.

We need a loading.hbs file of some kind. If someone has designer-y tendencies to make it look good that would be great as well. Sorry to be vague; I don't know what I want. :\

in current implementation we use the link-to active indicator to highlight selected tabs. This works fine when clicking tabs, but not when linking from the index (because of individual subroutes) we need to keep the tab active.

To do this we can create a helper that prints each sub route of a tab. Something like current-when=(list-routes model (concat parentName ".events")

For some reason as @fivetanley and I were working together today, the Heroku app went down. It'll need to be back up before we can make much more progress here ...

So that folks know where the data for this comes from (https://github.com/ember-learn/ember-jsonapi-docs)

This issue is intended for the Ember Denver Meetup tonight!

@kimroen has created an excellent addon based on @machty's work. The addon is here:

https://github.com/kimroen/ember-cli-document-title

To install it, you can run ember install ember-cli-document-title.

There's a couple places we'd need to add this:

• https://github.com/fivetanley/ember-api-docs/blob/master/app/routes/project.js
• https://github.com/fivetanley/ember-api-docs/blob/master/app/routes/project-version.js
• https://github.com/fivetanley/ember-api-docs/blob/master/app/routes/project-version/class.js

The final result should be something like Ember.Object - Ember 1.13 - Ember API Docs.

You should be able to achieve something like this with the following code (stolen from the addon's README):

// routes/application.js
export default Ember.Route.extend({
  title: function(tokens) {
   return tokens.reverse().concat(['Ember API Docs']).join(' ');
  }
});