rust-lang / docs.rs

crates.io documentation generator
https://docs.rs
MIT License
997 stars 198 forks source link

Enable playground for crates that are available there #1508

Open Nemo157 opened 3 years ago

Nemo157 commented 3 years ago

When a crate is available in https://play.rust-lang.org we could add the --playground-url argument so that its examples get the "Run" button enabled. The list of crates currently supported is at https://play.rust-lang.org/meta/crates (@shepmaster are you ok if we use this url? (with appropriate fallback in case it changes)).

One small complication is crates that have multiple versions available:

    {
      "name": "ansi_term",
      "version": "0.12.1",
      "id": "ansi_term"
    },
    {
      "name": "ansi_term",
      "version": "0.11.0",
      "id": "ansi_term_0_11_0"
    },

the playground puts older versions under a renamed extern, so we wouldn't want to link them. This probably means we just need to do a lookup based on the id == lib_name and then semver comparison that it's within the same semver compatible range (in either direction, since docs will generally be built for a newer version before it gets deployed to the playground).

The bigger complication is that we would be making static data linking to dynamic data, crates come and go from the playground, and it updates their versions all the time. I think it's probably still worth it, from what I've seen the playground crate list changes slowly enough that I think the upside of having the button when it works will outweigh the times it doesn't.

jyn514 commented 3 years ago

If it really changes that slowly, we could probably just rebuild the crates when they're removed, it sounds like it would only be 10 or so at a time.

Nemo157 commented 3 years ago

It's once a month, but I haven't looked at how many added/removed/major version changed per update: https://github.com/integer32llc/rust-playground/commits/master/compiler/base/Cargo.toml

shepmaster commented 3 years ago

are you ok if we use this url? (with appropriate fallback in case it changes)).

Yes. Ideally you'd only query it at a low frequency to avoid undue load — as you noticed, it doesn't change frequently anyway.

It's once a month

I wouldn't ascribe any particular frequency to it, however. It's basically some mix of:

  1. A new stable Rust version comes out
  2. A crate gets yanked
  3. I want some new version of a crate for an arbitrary reason
jyn514 commented 3 years ago

@shepmaster is once a day infrequently enough?

shepmaster commented 3 years ago

Yeah, that should be fine. We actually cache it on the web server side with a frequency of an hour.