Tracking Issue for RFC 1826: Change the default URL of doc.rust-lang.org

[steveklabnik]

This is a tracking issue for the RFC 1826 (rust-lang/rfcs#1826).

Steps:

• Implement the RFC
• Switch doc.rust-lang.org over, which is sort of "stabilization" in this case.

Unresolved questions:

No official ones, but there will undoubtedly be tweaks during implementation.

NB: a prototype is at https://rust-docs.herokuapp.com, source here: https://github.com/steveklabnik/rust-docs This can serve as a starting point for discussing said details, but does not literally have to be the basis of implementation.

[kornelski]

The prototype behaves like <frameset> without exposing useful URLs. That's very problematic for me, since I can't copy/share/bookmark documentation pages.

I hope that lack of user-visible URLs is just a rough edge of the prototype rather than part of the solution (I don't quite understand the RFC, I feel like I'm missing context for it).

[steveklabnik]

I hope that lack of user-visible URLs is just a rough edge of the prototype rather than part of the solution

Yes, absolutely.

[kzys]

Seems we already have https://doc.rust-lang.org/1.29.0/, https://doc.rust-lang.org/1.28.0/, ... The only missing part here is having a small header on each docs, which can be implemented as a small JavaScript file.

How we can update the JavaScript file and probably https://doc.rust-lang.org/index.html to list all releases? We may be able to generate them from rust-lang/rust's nightly (assuming that the latest nightly includes all stable releases), or have a separate repository.

[kzys]

I made a small demo to show how it would look. The version picker itself doesn't work still. The main purpose of the demo is discussing about the look & feel first.

http://rust-pull-request.s3-website-us-east-1.amazonaws.com/44687/std/

• Version picker is in the page itself, inserted by JavaScript (no iframe)
• The picker is "sticky", always shown on the page since Rust is evolving fast still.
• The version information is hosted as a static JSON file on doc.rust-lang.org (not implemented)

[steveklabnik]

Hey @kzys , thanks for poking at this!

What exactly does

Version picker is in the page itself, inserted by JavaScript

mean? How is it inserted by JS?

[kzys]

I meant, having all versions links on rustdoc's HTML files would not work, since we want to have links to older docs to newer docs (and vice versa, of course). We would not want to update all docs on every release. So, the implementation would need 1. a JSON file that lists all releases (like thanks.rust-lang.org) 2. a small JavaScript to read the JSON file, construct a drop-down. 3. include the JavaScript file from rustdoc's HTML to show the dropdown if the location is docs.rust-lang.org Not sure sure where would be the best place to generate 1. 2 and 3 could be implemented as a part of rustdoc.

[steveklabnik]

Right, so the issue here is:

include the JavaScript file from rustdoc's HTML

We have already produced the HTML for those old releases, and they can't change. So this approach would work going forward, but wouldn't work for releases previous to that.

[kzys]

I see. Would it be able to edit the generated docs to include the JavaScript file? That's not ideal though. Another option is having a menu item to say "for older releases, please see ..." that links to a static page which lists all releases, but the version picker is needed for especially older releases.

[steveklabnik]

That's not ideal though.

Yeah, we have a hard constraint on not being able to do this.

"for older releases, please see ..."

The issue with that is that it doesn't solve one of the primary motivations for doing this: people seeing older versions and not realizing they're out of date.

[kzys]

If changing the old docs is not possible, the remaining options are;

• Dynamically replace docs's certain parts via a http server (like https://httpd.apache.org/docs/2.4/mod/mod_substitute.html or http://nginx.org/en/docs/http/ngx_http_sub_module.html), not so sure what we are using though.
• frame/iframe

Would you mind if I ask the reason of not changing the old docs? I agree we shouldn't do that daily/monthly basis, but what if the change is only once?

[steveklabnik]

Reproducibility is important, and so releases are immutable. I’m starting to think the server side idea is the best option...

…

On Oct 5, 2018, at 11:45 AM, Kazuyoshi Kato ***@***.***> wrote: If changing the old docs is not possible, the remaining options are; Dynamically replace docs's certain parts via the http server (like https://httpd.apache.org/docs/2.4/mod/mod_substitute.html or http://nginx.org/en/docs/http/ngx_http_sub_module.html), not so sure what we are using though. frame/iframe Would you mind if I ask the reason of not changing the old docs? I agree we shouldn't do that daily/monthly basis, but what if the change is only once? — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub, or mute the thread.

[kzys]

Thanks! That make sense.

Does doc.rust-lang.org use S3 + CloudFront according to the HTTP headers? Not so sure since the old issues sometimes mentioned "rewriting". On CloudFront, we may be able to use Lambda@Edge instead of spinning up a http server.

(Disclaimer - I work for Amazon, but not AWS)

[steveklabnik]

doc.rust-lang.org use S3 + CloudFront according to the HTTP headers?

Yep!

On CloudFront, we may be able to use Lambda@Edge instead of spinning up a http server.

That is an intriguing idea!

[Mark-Simulacrum]

FWIW, I think fixing this by including an empty just file from some common location or path that we can update later (e.g. rust-lang.org/doc-1.23.0.js) would be good. The other side of this is I think changing old HTML files uniformly isn't a bad thing: for one thing it's cheaper than any other solution from a monetary perspective and I don't quite see why it would pose too large a problem. We're not changing static.r-l.o artifacts which I think are far more critical to keep constant vs. docs.r-l.o artifacts...

[steveklabnik]

We're not changing static.r-l.o artifacts

Oh? I thought they were identical. If this is not the case, then I feel like there's more wiggle room.

[Mark-Simulacrum]

Yes, the docs are served from a different bucket in s3, I'm fairly sure, and if they weren't, we could "easily" start doing so.

[steveklabnik]

Okay, then maybe that is the path forward, then.

[kzys]

Is it easy to have a file inside the bucket, like docs.rust-lang.org/common/footer.js ? If so, we can create the file first, reference from the nigltly docs by changing rustdoc, and replace all old docs later to include the file. In addition to that, if we have a specific update script for the bucket, we probably don't have to change rustdoc.

[dustinknopoff]

I'd like to take a stab at this. I'm a little unclear as to where to start from.

I was thinking @kzys way of injecting some JS in to the existing versions would be best.

I'd also like to suggest doing something like one of the two mockups above on the version badge on doc.rust-lang and/or on the actual documentation as well.

[kzys]

Thanks @dustinknopoff!

I'm working on an actual prototype based on the mock. You can try that by copy-and-paste the below JavaScript from browser's console.

s=document.createElement('script');s.type='text/javascript';s.src='https://blog.8-p.info/en/tmp/2019/rustdoc-version-selector.js';document.body.appendChild(s);

The script only supports doc.rust-lang.org's landing page such as https://doc.rust-lang.org/1.31.0/ so far.

My thoughts;

• While reusing the existing version information looks nice, the coupling between this script and the DOM structure is a bit concerning, in terms of maintenance.
• What do we want to have in the combo box? @steveklabnik's initial prototype only has stable, beta, nightly. https://docs.python.org/3/ has 5 versions and I don't know why these five. My prototype shows all releases as is, which may be confusing.