ember-learn / ember-api-docs

Ember API Docs viewer

Ember API Docs

This project contains only the API docs portion of Emberjs.com. If you're looking for the rest of the site, see the website and guides repositories.

There are many pieces that together create the Ember API docs site:

• The app in this repository, which fetches and displays the API docs data. It is what you see at https://api.emberjs.com/
• The YUIdoc code comments found in the Ember.js codebase, where the informational content of the API documentation can be edited
• The data generator that serializes code comments into JSONAPI and deploys the result, ember-jsonapi-docs
• ember-styleguide, a component and styling library shared across apps.
• algolia-index-update-scripts for managing the search feature of the api docs site

Contributing

New contributors are welcome! This project is maintained by an all-volunteer team, and we are thankful for your help.

The best way to get started is to find an issue labeled "good first issue" or "help wanted." If you have questions or want a buddy to pair with, drop by the #dev-ember-learning channel on the Ember Community Discord. Like most open-source projects, contributors are encouraged to open an issue to propose changes and iterate on ideas before investing time in coding. Some tips for working with git/GitHub can be found in Making your first pull request in the Guides repository.

Please also see CONTRIBUTING.md.

Running in your local environment

ember-api-docs expects a folder in its root that links to the ember-api-docs-data folder, so you can either use the npm run clone script to clone the ember-api-docs-data repo into ember-api-docs, OR you can create a symbolic link to ember-api-docs-data from ember-api-docs. You might want to sym-link ember-api-docs-data if you are generating new versions of the docs files with ember-jsonapi-docs, otherwise you can probably use the clone script.

Quickstart to run locally

Follow these instructions to run the app using publically available online data. You do not need to run ember-jsonapi-docs locally yourself.

git clone https://github.com/ember-learn/ember-api-docs.git
cd ember-api-docs
npm install
npm run clone
npm run start

View at http://localhost:4200

Run locally with a sym-link

Clone all of the following repositories into the same directory so they are "siblings" on the file system:

• This repository, ember-api-docs
• ember-api-docs-data

git clone https://github.com/ember-learn/ember-api-docs-data
git clone https://github.com/ember-learn/ember-api-docs
cd ember-api-docs
ln -s ../ember-api-docs-data
npm install
npm start

Visit the app in your browser at http://localhost:4200

a11y testing

To run a11y tests, run test_a11y=yes ember serve

Linting

• npm run lint:hbs
• npm run lint:js
• npm run lint:js -- --fix

Staging and Deployment

See the DEPLOYING.md guide for instructions.

Building

Cross-browser testing provided by:

ember-api-docs's Issues

Make "scroll reset on transition" acceptance test pass

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

Don't eat up user's data bandwidth quota

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.

Private classes show up under Modules when not checked in sidebar

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

Show main sections above our property, methods section

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

Clicking on certain classes hides the left nav menu

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

Inheritance information is not properly generated in the docs generator

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.

Layout is too wide on larger screens

Layout should be limited to a maximum width

Show inherited, private, protected and deprecated filters

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

Dropdown of versions should be minor version only

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.

Redirected to 2.9.1, not 2.10.0 on first visit

Remove the searchbar

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

Should modules come before namespaces?

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.)

Add info about the docs generator to the Readme

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

fix favicon

Show the various pieces of data up in the header that relate to a class

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

Needs a 404 state

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

activate tab when switching by clicking item in index

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")

Namespace/Module Incosistencies

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

Add a `projects` section to the page

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

Reset scroll to top when navigating routes

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.

Modules should show parent link

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

Update to a more recent version of fastboot

Currently using 0.6

When switching databases or when databases are updated, local PouchDb doesn't sync.

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

css: lists rendered 2 columns

New app:

Original:

Show modules and namescapes on the sidebar

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

Replace deprecated EmberApp.concatFiles() calls with broccoli-concat

getting the following on startup:

Classes list should expand/unexpand like on the guides site

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)

Add the "Edit on Github" pencil icon in again

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.

Setup CD deploys of this app

Need formatting in details

Example in current api docs:

Example in app:

Favicon.ico

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

Get the Heroku app back up and running

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 ...

Remove private classes from sidebar

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.

When visiting the home page, we should redirect to the *latest* version

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.

Hide Section in Modules when none exist.

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:

Decide whether to show inherited private methods as we do currently

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 😄

Error page

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

Setup the ability to click a method name and jump to the appropriate section of the page

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.

opengraph tags for methods/events/properties should have more information

right now they don't show anything

Setup CD deploys of the backend

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

Add in the Algolia search box

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

Display visibility information for each method

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 ...

Add document.title integration

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(' ');
  }
});

main layout scrolls behind top banner, messes with anchoring

Link to the appropriate code on Github for each method

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 ...

filter detailed methods/properties/events on toggle

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

Add eslint support

use ember-cli-eslint to ensure conventions.

Whatever core uses should be fine.

Hide / disable the search box if someone is offline and using the api viewer

Loading state

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. :\

hide private toggles for public deployment

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.