ember-learn/ember-api-docs

404 / missing EmberData API docs of old releases

bastimeyer opened this issue · 9 comments

bastimeyer commented

When trying to find old documentation for Ember-Data, error 404 gets returned.

There appear to be two separate issues:

  1. The latest docs seem to have a "new" start page for an overview of the ED API docs, and when trying to switch the version from that start page to a version where that page doesn't exist, this will lead to a 404
  2. Anything below 3.11 doesn't seem to be available at all anymore, which is pretty bad.
jenweber commented

Thanks for reporting! I see the same issues as you. I’ll bring this up with the team for troubleshooting ASAP.

jedateach commented

@jenweber Yes, please.

jenweber commented

The original issue reported by @bastimeyer has been resolved via bugfix for a github URL issue, and version switching 404s are intended behavior (see note below).

@williamhector thanks for dropping by to report the problems with these other links. The issue you pointed out is separate from bastimeyer's links, but does seem to be a real problem! I'll look today. In general, we highly prioritize maintaining and fixing active LTS versions on up. However as the last release of v2, I'd like to see 2.18 docs working ok to aid people in upgrades.

Note: when documentation URLs change between versions due to changes in source code documentation and file structure, trying to switch between those versions will cause a 404. This is expected behavior. We do not create redirects between versions. The best way to get to the docs for a specific version is through navigating to a specific version and using the search/sidebar, instead of locating the docs on a different version and then trying to version switch. However, if a page is broken even from the link in the sidebar, that is indeed a real bug and not intended behavior.

jenweber commented

I confirmed that a bunch of 2.18 docs don't render. It appears that the docs json itself is missing for those classes, which is not a quick fix as far as I can tell. I'll be continuing to focus on work to get our docs out of AWS and into GitHub, so we can edit them and fix many things like this more easily in the future. That means I am not going to be debugging 2.18 further. If anyone is interested in helping to debug, the steps are:

  1. Generate docs locally for this version using the ember-jsonapi-docs repo and instructions https://github.com/ember-learn/ember-jsonapi-docs#generate-docs-from-ember-source
  2. Serve the results using yarn serve in that repo
  3. Run this ember-api-docs app with yarn start:local
  4. Compare behavior and json content with production network requests
jenweber commented

Also if anyone wants to follow along on the more meta effort to fix API docs issues in general, see #815 which is a work-in-progress, but definitely making good progress!

EWhite613 commented

Looks all of 3.x has this issue now @jenweber . Tested a bunch of 3.16 and 3.28 pages, both ember data and ember

This breakage seems to be new for those, as was looking at them a week ago with no issue

mansona commented

once ember-learn/ember-api-docs-data#16 is merged it will fix everything on ember-data 🎉