Add copy button for code blocks

[GuillaumeGomez]

As discussed in #86363, we could add a button allowing to copy the content of the source code. For this, I'll unify the content for the "run" button as well so it's not duplicated in case the run button is there as well. Or we could simply generate the button content when clicking on it using JS (because the "copy to clipboard" can only be done with JS), meaning we also generate the hidden lines (but keep them invisible).

Second point: for now the "run" button is always visible but its opacity goes to 1 when you hover it. I'll change this behaviour by hiding those buttons and only making them appear when hovering the code example so it improves the reading experience. However, I'll keep the opacity change behaviour when going on top of the button.

Last thing: should we add this copy button to all code blocks or only the rust ones?

cc @rust-lang/rustdoc

[Manishearth]

So i think having just a regular copy button for copying the examples as shown would be nice. However I think in #86363 folks were discussing this as a way to show the "hidden" code that's in examples to make them run -- I don't think a "copy" button should ever copy text that it is not being displayed.

I do think if we want to make the hidden text visible we should have an "expand" button that shows greyed-out code. The copy button could still copy the hidden text when in expanded mode.

[jsha]

Agreed that we should only copy visible text. Here's an idea: when you click the "copy" button it shows "Copied ✓. To reveal and copy hidden boilerplate, click here." And it could show the latter part only when there actually is hidden boilerplate.

[Manishearth]

Would be weird to only expose the "reveal hidden boilerplate" option when you click copy, I'm thinking adding a second button with an "expand" icon on it

[GuillaumeGomez]

I can do that as well. I already have the code ready for the "copy to clipboard" so I can add an expand button as well.

[camelid]

I read through this thread and the linked playground-url PR, but I wasn't able to find a description of why the copy and expand features would be useful. I would like to understand better why people want this feature. I feel a bit concerned because the buttons add some visual weight to the docs, and as we've discussed before, the docs already have a lot of visual components that make them harder to read. For me personally, I have very rarely wanted to copy and paste an example or see the hidden code. My understanding is that hidden code is usually an "implementation detail" of the example, and shouldn't be displayed to the reader.

I'm open to the idea, I would just like to understand where people are coming from :)

[GuillaumeGomez]

I originally wanted to add the "run" button in every case to be able to have all the code so I can edit it (fully, not just the visible part). This is often an issue when copying/pasting code which lacks the "implementation details" because then you have to look again what's missing, mostly in cases where ? is used. Therefore it was suggested to simply add a button to copy it and another one to expand/collapse the code block.

As for the visual weight, I intend to make all the code blocks' buttons hidden by default until you hover the code block. That should reduce the visual weight quite a lot.

[jsha]

Bringing over part of @camelid's comment

Part of why I don't understand the use case is that I find that most code examples I look at can't just be copied and pasted into my code; only a small piece, say a function call, is relevant, and that I can type myself. For example, with Iterator::filter(), most of the examples are just setup and assertions to demonstrate the function in context. Nothing except .iter().filter() would be relevant to my code, so I wouldn't copy-and-paste.

Here are a couple of counterexamples from popular crates, of code you might want to copy-paste and then modify:

https://docs.rs/log/0.4.14/log/#implementing-a-logger

use log::{Record, Level, Metadata};

struct SimpleLogger;

impl log::Log for SimpleLogger {
    fn enabled(&self, metadata: &Metadata) -> bool {
        metadata.level() <= Level::Info
    }

    fn log(&self, record: &Record) {
        if self.enabled(record.metadata()) {
            println!("{} - {}", record.level(), record.args());
        }
    }

    fn flush(&self) {}
}

https://doc.rust-lang.org/std/net/struct.TcpStream.html#examples

use std::io::prelude::*;
use std::net::TcpStream;

fn main() -> std::io::Result<()> {
    let mut stream = TcpStream::connect("127.0.0.1:34254")?;

    stream.write(&[1])?;
    stream.read(&mut [0; 128])?;
    Ok(())
} // the stream is closed here

https://docs.serde.rs/serde_json/#creating-json-by-serializing-data-structures

#[derive(Serialize, Deserialize)]
struct Address {
    street: String,
    city: String,
}

fn print_an_address() -> Result<()> {
    // Some data structure.
    let address = Address {
        street: "10 Downing Street".to_owned(),
        city: "London".to_owned(),
    };

    // Serialize it to a JSON string.
    let j = serde_json::to_string(&address)?;

    // Print, write to a file, or send to an HTTP server.
    println!("{}", j);

    Ok(())
}

That said, browsers do provide built-in functionality to copy-paste, so the question is: does adding a "copy" button to each code block make copying easier by enough of a margin to be worth the screen real estate?

@GuillaumeGomez, one thing that might help resolve some of the team's ambivalence about the feature would be to talk to some other people who have a need for this feature. Do you know other folks who expect to find it useful?

[GuillaumeGomez]

Mostly people I talked to directly when we met. We can always propose a poll and put the link on twitter, reddit and the rust forums?

[Manishearth]

I don't actually think that'll work. When you ask most people "what do you think of feature X", you'll get a response of either excitement or ambivalence, folks are not often against new features, which skews the dataset towards people who want it. OTOH as a product team we have to be careful to not just randomly add features; we need to make sure we're filling a need and balance that against our ability to maintain things.

As I said here, we need to focus on the actual problems people are facing without getting ahead of ourselves with solutions. If we're going to be surveying users, we should ask around for what kind of challenges people face in this area, if at all, and keep in mind that the only people who respond will be ones with challenges.

[jsha]

Here's my attempt at it:

Problem 1: As a new user, if I copy an example from a crate's documentation on docs.rs, sometimes it doesn't compile because it uses ?, but the fn main() -> Result<_> { wrapper is hidden, and I don't know I need to add it.

Problem 2: As an experienced user, if I copy an example from a crate's documentation, sometimes it doesn't compile because it relies on hidden use statements, and it's hard to find out which use statements I need to write to make it work.

Problem 3: As an intermediate user, if I copy an example, sometimes it doesn't compile because it relies on hidden #[allow(unused)] or #[allow(dead_code)].

[Manishearth]

Thanks, but stepping back I mean to say that if we're going to be surveying users we should figure out if these are problems they face, and how.