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

2cd17d9
Opened by Steve Klabnik at 2022-03-18 16:48:37

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.

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

    Kornel at 2017-12-05 19:01:16

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

    Yes, absolutely.

    Steve Klabnik at 2018-02-06 14:55:46

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

    Kazuyoshi Kato at 2018-09-27 06:45:10

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

    Kazuyoshi Kato at 2018-09-30 00:00:30

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

    Steve Klabnik at 2018-10-05 14:52:08

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

    Kazuyoshi Kato at 2018-10-05 15:03:55

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

    Steve Klabnik at 2018-10-05 15:05:35

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

    Kazuyoshi Kato at 2018-10-05 15:25:49

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

    Steve Klabnik at 2018-10-05 15:35:37

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

    Kazuyoshi Kato at 2018-10-05 15:45:36

  11. 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 notifications@github.com 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.

    Steve Klabnik at 2018-10-05 16:00:36

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

    Kazuyoshi Kato at 2018-10-05 16:10:40

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

    Steve Klabnik at 2018-10-05 16:32:05

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

    Mark Rousskov at 2018-10-05 16:45:48

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

    Steve Klabnik at 2018-10-05 16:51:04

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

    Mark Rousskov at 2018-10-05 16:58:26

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

    Steve Klabnik at 2018-10-05 16:59:46

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

    Kazuyoshi Kato at 2018-10-05 17:11:52

  19. 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. <img width="597" alt="screen shot 2018-12-28 at 10 19 17 am" src="https://user-images.githubusercontent.com/23691663/50519729-458ace00-0a8a-11e9-83c1-090e21f85132.png">

    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.

    Dustin Knopoff at 2018-12-28 15:10:43

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

    Kazuyoshi Kato at 2019-01-02 06:32:20

  21. For the people subscribed to this issue: @GuillaumeGomez made a crack at it in https://github.com/rust-lang/rust/pull/58603, though it may be different than what was being planned here.

    QuietMisdreavus at 2019-02-25 16:02:23

  22. Completely forgot about this one actually. :-.

    Guillaume Gomez at 2019-02-25 16:43:28

  23. I'm going to go ahead and assign this to @rust-lang/infra, but it might make more sense under T-rustdoc?

    Jack Huey at 2022-03-18 16:45:06

  24. It's both so it's a good idea to include them as well.

    Guillaume Gomez at 2022-03-18 16:46:56