Sphinx-copybutton

Sphinx-copybutton does one thing: add a little “copy” button to the right of your code blocks. That’s it! It is a lightweight wrapper around the excellent (and also lightweight) Javascript library ClipboardJS.

Here’s an example

And here’s a code block, note the copy button to the right!

copy me!

If the code block overlaps to the right of the text area, you can just click the button to get the whole thing.

123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789

You can configure sphinx-copybutton to detect input prompts in code cells, and then both remove these prompts before copying, as well as skip lines that don’t start with prompts (in case they are output lines).

For example, this site has been configured to strip Python prompts (“>>> “) and output lines. Try copy-pasting the code block below.

>>> a = 2
>>> print(a)
2
>>>
>>> b = 'wow'
>>> print(b)
wow

Install

You can install sphinx-copybutton with pip:

pip install sphinx-copybutton

Or with conda via conda-forge:

conda install -c conda-forge sphinx-copybutton

Here’s a link to the sphinx-copybutton GitHub repository.

Use

In your conf.py configuration file, add sphinx_copybutton to your extensions list. E.g.:

extensions = [
    ...
    'sphinx_copybutton'
    ...
]

When you build your site, your code blocks should now have little copy buttons to their right. Clicking the button will copy the code inside!

See Use and customize for more information about how to use sphinx-copybutton.

• Use and customize
  • Strip and configure input prompts for code cells
  • Keep empty lines
  • Multi-line snippets
  • Change the icons
  • Add or remove copy buttons to any element with a CSS selector
  • Modify the copy button’s style with CSS
  • Exclude text from being copied
• Contribute
  • Code style
  • JavaScript unit testing
  • Documentation builds
• Reference examples
  • Code Cells
  • Tables
  • MyST Notebook Cells
  • Rough edges
• Changelog
  • v0.5.1 - 2022-11-15
  • 0.5.0 - 2022-02-05
  • 0.4.0 - 2021-07-03
  • 0.3.2 - 2021-06-11
  • 0.3.1 - 2020-11-02
  • 0.3.0 - 2020-07-25

Inspiration

The UI and design elements of sphinx-copybutton are heavily inspired by GitHub’s design choices. The icon we use is from Tabler’s icons set.