ember-learn / ember-api-docs Goto Github PK
View Code? Open in Web Editor NEWEmber API Docs viewer
Home Page: https://api.emberjs.com
License: MIT License
Ember API Docs viewer
Home Page: https://api.emberjs.com
License: MIT License
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)
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.
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.
References to namespaces that don't exist and other data issues break the app.
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 😄
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
To reproduce, click on Ember.ApplicationInstance, Ember.Controller, or Ember.CoreObject
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 ...
So that folks know where the data for this comes from (https://github.com/ember-learn/ember-jsonapi-docs)
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.
https://github.com/ember-learn/ember-api-docs/pull/117/files#diff-4fe440ae4dbaca7ea3e433eedb54fe76
So far this test fails on Travis most likely because either:
article
overflow:auto is not activeWorkaround: In applications tab of Chrome, clear the IndexedDb.
use ember-cli-eslint to ensure conventions.
Whatever core uses should be fine.
Currently using 0.6
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. :\
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.
Layout should be limited to a maximum width
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 ...
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")
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:
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(' ');
}
});
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.)
For example, when you navigate to https://ember-api-docs.herokuapp.com/lol1234, we should display a "Not found" page of some kind
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.
We need to steal the favicon.ico from emberjs.com or guides.emberjs.com and stick it in the public folder.
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.
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
Currently the filter checkboxes are only toggling items in the index. They should also toggle details.
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
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
When an error occurs in the application, we should display a "Whoops! Something went wrong." or similar page
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 ...
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.
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:
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.
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.
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
It doesn't currently show up in the header but should
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.