DOC Add a button to copy code (#12512)

[tuscland]

Reference Issues/PRs

Closes #12512.

What does this implement/fix? Explain your changes.

In the documentation, add a copy button to all code blocks.
When clicked, the text in the block is filtered in order to remove prompts (>>>) and output lines. Text without prompt is copied as-is.

Any other comments?

• The sphinx_copybutton extension was used.
• The default style draws an outline around the hovered button. To make it look better, a CSS declaration was added.

[github-actions]

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

_{Generated for commit: cdce63d. Link to the linter CI: here}

[betatim]

I think this is a nice change. The copybutton sphinx extension is quite widely used as well.

One thing to try and find out from the archives: what was the thinking "back then" to add a button that hides the prompts, instead of having one that copies the text to the clipboard? Is it an accident of history or was there some specific thinking about this aproach (hide and then let the user copy themselves).

[tuscland]

One thing to try and find out from the archives: what was the thinking "back then" to add a button that hides the prompts, instead of having one that copies the text to the clipboard? Is it an accident of history or was there some specific thinking about this aproach (hide and then let the user copy themselves).

I believe the "hide prompts" button allowed for more controlled copy & paste user experience, because when you copy a block of code and paste it all, you might miss intermediate results.

[ArturoAmorQ]

Nice addition! LGTM as it is. Thanks @tuscland.

[betatim]

If someone can find a way to customise the "copy" label that appears on the left when you hover the button (not the bottom label that comes from the browser) that would be great. We could use it to make it clearer to the (sceptical) user what exactly will be copied (only the inputs, not the outputs).

[tuscland]

If someone can find a way to customise the "copy" label that appears on the left when you hover the button (not the bottom label that comes from the browser) that would be great. We could use it to make it clearer to the (sceptical) user what exactly will be copied (only the inputs, not the outputs).

It would require to propose a change to sphinx-copybutton localized messages:
https://github.com/executablebooks/sphinx-copybutton/blob/4a8050dea36536b005d3e757b1ac09886174f634/sphinx_copybutton/_static/copybutton.js_t#L5

[ArturoAmorQ]

It seems that this PR still has an issue. The copy button ignores lines that start by .... For instance, the following code:

>>> train_scores, test_scores = validation_curve(
...     logistic_regression, X, y, param_name=param_name, param_range=param_range
... )

ends up copying only

>>> train_scores, test_scores = validation_curve(

[betatim]

I'll try and make a PR to repair this or revert this change.

[tuscland]

I understand ... is a continuation of the prompt, therefore we should use a different configuration for the sphix_copybutton plugin. Currently we have:

copybutton_prompt_text = ">>> "

@betatim as per the documentation, we could try this instead:

copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True