create url to the latest version of a generated doc package

[adam-singer]

http://www.dartdocs.org/documentation//latest/index.html

This link or folder would need to be updated upon each latest version published.

[adam-singer]

Maybe we could use http://www.dartdocs.org/latest/<package_name>/

[sethladd]

You want a long-lived canonical URL, specifically down to a class, but without a version number? What if version 2 of a package removes that class?

What if we setup a redirect from:

/latest/package-name/

and it 302 redirects to /package/version/

?

Are you OK if /latest/package-name/ resulting in a 404 at some later date (assuming foo was removed from a future version) ?

[sethladd]

cc @kevmoo

[adam-singer]

@sethladd to the best of my understanding if package-name changed then it would be a totally different package altogether. Are you thinking meta tag refresh? Not sure if cloud storage provides the configuration for 302.

[sethladd]

If package name changed, it's a wholly separate package in the eyes of pub. So I'm not too concerned about redirecting from old name to new name.

Do we want to support deep linking into API docs + a relative "latest" URL? Those two concepts are at odds.

[adam-singer]

@sethladd currently the only way I can figure having a latest is by wiping out the http://www.dartdocs.org/latest/<package_name>/* files and uploading a fresh version. One show stopper at the moment is making doc viewer client an artifact that is not built on every pub doc build. It made sense in the past when stuff was rocky in terms of command line options. I guess going forward the build of the dart doc viewer should be separate from the build of the docs data. Then at a later point in time join the two together and deploy to cloud storage. I think a major refactor should happen with the roll out of dart cloud. The downside of having the client as an artifact is its another resource to manage. https://github.com/financeCoding/dart-carte-du-jour/issues/81

[sethladd]

We can't delete a "directory" and upload a fresh version because we can't do an atomic swap. The only way I see us easily doing this is to setup a redirect.

Still, the open question that I'd like input from @kevmoo is are we OK with creating URLs that might break. /latest/foo/SomeClass is a URL that will break when SomeClass is deleted from a future version of foo.

Let's say we're OK with this. I assume we can do this with a redirect?

[kevmoo]

@sethladd I'm w/ you there.

If SomeClass goes away, then that lastest/foo/SomeClass link either 404s or redirects to the core project.

We all on the same page?

[sethladd]

OK, 404 or redirect if possible.

@financeCoding I'm sensitive to standing up a server just to do redirects, but I think we'll have to. If we do, we'll have to serve all links from our server, and the server will need to proxy the requests back into cloud storage. Basically, we're back to what we do for api.dartlang.org. It's a real pain, but I can't see another way.

Good news: we've figured it out with api.dartlang.org. And I think we can do it without breaking all the existing URLs.

But we'll need dartdocs.org/* to go through the a new HTTP server. sigh. Unless there's another way?

[adam-singer]

@sethladd using gsutil you can do gsutil rm -rf gs://www.dartdocs.org/latest/<package_name>/* and all files will be deleted after it completes. Not a huge deal for a single package, if we wanted to do gsutil rm -rf gs://www.dartdocs.org/latest/*, that could take some time..

My thought on 404 redirect without having a server in place would be to have a custom 404 page registered with cloud storage that has some compiled dart2js code that links to the root proect. Maybe include some blurb how that class might not exist anymore. How does that sound? Discussed something similar with @nex3 in a previous issue https://github.com/financeCoding/dart-carte-du-jour/issues/77

[sethladd]

@financeCoding my understanding is that gsutil rm -rf could take "a while" to complete. I'm worried about a user reading the docs and then clicking a link and POOF it's gone.

Interesting about a custom 404 page and a simple Dart app to look at the intended URL and "do the right thing". Cool idea! Anything so we don't have to put a server in place works for me.

[sethladd]

Bumping to High. This is blocking our ability to disable package docs on api.dartlang.org.

Minimum requirement here is ability to link to the homepage of the latest version of a package. That link should do a temporary redirect to whatever is the latest.

Second requirement is to be able to redirect into a specific class or method.

Any chance we could get this feature pretty soon?

[sethladd]

here's a ghetto way to do it:

when the build is successful, drop this file into cloud storage:

/documentation/foo/latest

contents:

<meta http-equiv="refresh" content="0; url=https://www.dartdocs.org/documentation/foo/version">

Problem is, search engines won't pick it up (maybe they will?)

Another problem: doesn't allow deep linking. Unless you serve up an HTML with a bit of JS which dynamically does the redirect (as you mention above).

Should we try it?

[adam-singer]

@sethladd What packages will be disabled on api.dartlang.org? Currently only see the dart:* packages on that site.

What does the following mean? "Second requirement is to be able to redirect into a specific class or method." Redirect if the class does not exist to the latest package root? Does it need to really smart in terms of redirect of a missing method on a class to the class documentation?

I think its possible to get something out this week.

Will need to build two things. One that copies all the latest documentation over to the latest folder. Another thing that copies the latest after a package is built. The second part needs to be a little smart, it cant just copy the latest package built cause we have ability to build package documentation out of order. It will need to be smart enough to query for the latest version of the built documentation and copy that.

I think uploading the latest html is a better route then meta redirect.

[sethladd]

@financeCoding there is a small "show packages" option in api.dartlang.org. If you toggle that, a whole ton of new package docs show up. We want to remove this :)

Second requirement: something like:

http://www.dartdocs.org/documentation/a_star/latest/index.html#a_star/a_star.Graph ==>

http://www.dartdocs.org/documentation/a_star/0.3.0/index.html#a_star/a_star.Graph

That is, redirect a "latest" link with a class name to the specific version URL.

If you can avoid copying packages, that would be awesome. But whatever works.

Thanks Adam!

[adam-singer]

Ok, then I will do the meta tag first if you think its best to avoid the copying. Wasn't sure how unholy meta refresh is considered these days.

[sethladd]

Let us know if you can do meta refresh and redirect to a class. Whatever works. We can turn caching up very high for the version specific files. Caching for latest can't be that high if we're using real files in latest.

[adam-singer]

@sethladd the latest urls are generating now. http://www.dartdocs.org/documentation/box2d/latest/index.html

[adam-singer]

regenerating all of them should be complete in an hour or so.

[kevmoo]

AWESOME. Thanks, Adam. :metal:

[sethladd]

Excellent!!

What is the cache time for latest?

[adam-singer]

No cache has been set since that redirect file could be updated frequently

[adam-singer]

Both latest redirect and deep linking of redirect with hash could be functional now. Regenerating the index files, closing out issue as complete?

Example

http://www.dartdocs.org/documentation/angular/latest/index.html#angular/angular-tracing@id_traceDetectWTF

will link to

http://www.dartdocs.org/documentation/angular/0.14.0/index.html#angular/angular-tracing@id_traceDetectWTF