docs: Add copy buttons to code snippets in docs with sphinx-copybutton

[matthewfeickert]

Description

Add sphinx-copybutton to the docs extra to add copy buttons to all code snippet blocks.

Thanks for tweeting and for the great work, @choldgraf!

This makes all of our docstrings even nicer now as the copy button removes the Python REPL prompts:

so that when pasted you get

import pyhf
pyhf.set_backend("pytorch")
a = pyhf.tensorlib.astensor([-2, -1, 0, 1, 2])
pyhf.tensorlib.clip(a, -1, 1)

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add sphinx-copybutton to docs extra
* Enable sphinx-copybutton in docs to add copy buttons to code snippets

[lukasheinrich]

does this also copy the output of the command? e.g. tensor([-1., -1., 0., 1., 1.]) if it's possible to just copy input data that'd be preferable

[choldgraf]

Current sphinx-copybutton just copies whatever is inside the code cell (minus stripping out some characters like prompts). If there's a way to know what part of the code cell should be skipped entirely (e.g. because it's an output), I'd be open to a PR in sphinx-copybutton that implements it! Here's the JS function that does the text copying:

https://github.com/choldgraf/sphinx-copybutton/blob/master/sphinx_copybutton/_static/copybutton.js#L65

[lukasheinrich]

thanks @choldgraf! at least for python shouldn't it be safe to say everything that does not start with >>> (the prompt) or ... (the continuation of a prompt) is an output?

[choldgraf]

@lukasheinrich it would be if all projects used >>> for their inputs, but a lot of them don't :-/

A lot of projects just dump raw code in there (so no prompts at all)

[codecov]

Codecov Report

Merging #721 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #721   +/-   ##
=======================================
  Coverage   95.89%   95.89%           
=======================================
  Files          54       54           
  Lines        2998     2998           
  Branches      424      424           
=======================================
  Hits         2875     2875           
  Misses         78       78           
  Partials       45       45

Flag	Coverage Δ
#unittests	95.89% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 51988a9...dbad9f1. Read the comment docs.

[kratsg]

@lukasheinrich it would be if all projects used >>> for their inputs, but a lot of them don't :-/

A lot of projects just dump raw code in there (so no prompts at all)

@choldgraf , a simple way is to add a configuration to allow for the last line to be copied or skipped. This should handle both cases. Additionally, could add a configuration indicating if the project wants to use >>> and ... so then you can just not copy lines that don't start with that.

[matthewfeickert]

a simple way is to add a configuration to allow for the last line to be copied or skipped. This should handle both cases. Additionally, could add a configuration indicating if the project wants to use >>> and ... so then you can just not copy lines that don't start with that.

Maybe we should make an issue over at sphinx-copybutton and ask Chris to assign one of us to it.

[choldgraf]

I think I'd be +1 on that idea @kratsg - we'd need to think through the potential use-cases. We'd need to consider whether there is a case that someone wants to copy the stuff after prompts, and also the stuff that comes after that. +1 on opening an issue to discuss there

[matthewfeickert]

Additionally, could add a configuration indicating if the project wants to use >>> and ... so then you can just not copy lines that don't start with that.

Just checking up on this tonight, and as @choldgraf is 💯% awesome, he already did all this — thank you Chris! 🎉 As of sphinx-copybutton PR 58 (which translated to sphinx-copybutton v0.2.9 on PyPI)

By default, if sphinx-copybutton detects lines that begin with code prompts, it will only copy the text in those lines (after stripping the prompts). This assumes that the rest of the code block contains outputs that shouldn’t be copied.

so the example for clip

now gives when pasted

import pyhf
pyhf.set_backend("pytorch")
a = pyhf.tensorlib.astensor([-2, -1, 0, 1, 2])
pyhf.tensorlib.clip(a, -1, 1)

@lukasheinrich @kratsg To see this in action, c.f. the Read the Docs build: https://pyhf.readthedocs.io/en/docs-use-sphinx-copybutton/index.html