Sphinx-copybutton

Documentation PyPi page

Sphinx-copybutton does one thing: add little “copy” button to the right of your code blocks. That’s it!

Here’s an example

_images/copybutton.gif

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

Installation

You can install sphinx-copybutton with pip:

pip install sphinx-copybutton

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

Usage

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!

Customization

Sphinx-copybutton was designed to work with the default Sphinx theme, Alabaster. If you use a theme that doesn’t play nicely with sphinx-copybutton’s CSS, you can always add your own CSS rules!

Customize the CSS

To customize the display of the copy button, you can add your own CSS files that overwrite the CSS in the sphinx-copybutton CSS rules. Just add these files to _static in your documentation folder, and it should overwrite sphinx-copybutton’s behavior.

Use a different copy button image

To use a different image for your copy buttons, the easiest thing to do is to add a small bit of javascript to your Sphinx build that points the image to something new. Follow these steps:

  1. Create a new javascript file in your site’s static folder (e.g., _static/js/custom.js). In it, put the following code:

    const updateCopyButtonImages = () => {
        const copybuttonimages = document.querySelectorAll('a.copybtn img')
        copybuttonimages.forEach((img, index) => {
        img.setAttribute('src', 'path-to-new-image.svg')
        })
    }
    
    runWhenDOMLoaded(updateCopyButtonImages)
    
  2. Add this javascript file to your conf.py configuration like so:

    def setup(app):
       app.add_javascript('js/custom.js');
    

This will replace the copybutton images each time the page loads!

If you know of a better way to do this with sphinx, please don’t hesitate to recommend something!

Development

If you’d like to develop or make contributions for sphinx-copybutton, fork the repository here:

https://github.com/choldgraf/sphinx-copybutton

pull to your computer and install locally with pip:

pip install -e /path/to/sphinx_copybutton

Pull requests and Issues are absolutely welcome!