Sphinx Copybutton

0.5.2 · active · verified Thu Apr 09

sphinx-copybutton is a Sphinx extension that adds a 'copy' button to each of your code cells in Sphinx documentation. It is currently at version 0.5.2, actively maintained, and releases generally align with bug fixes, minor enhancements, or updates to stay compatible with Sphinx itself.

Warnings

breaking In v0.3.0, the handling of `copybutton_prompt_text` regex strings changed to use raw string formatting. This required users to update their `copybutton_prompt_text` string to remove previous 'double escaping'.
Fix: Review your `copybutton_prompt_text` configuration. If you were double-escaping backslashes, you now only need a single escape (e.g., `"\\$ "` became `"\$ "`). Refer to the v0.3.0 release notes.
gotcha Starting with v0.5.0, the copy button design was updated to match GitHub's behavior, and the SVG icon is directly inserted into the HTML instead of being linked via an `<img>` tag. This can break custom CSS that targeted the `<img>` element for styling the button.
Fix: Update any custom CSS targeting the copy button to reflect the new SVG-based structure. You may need to target the `svg` element or its parent container directly. Inspect the generated HTML to identify the correct selectors.
gotcha In v0.5.2, a bug fix reversed the default exclusion of the `.gp` class from copy button processing. This change might unintentionally include prompt text in copied code for users who previously relied on `.gp` to be excluded by default.
Fix: If you use code blocks with `... prompt` directives (which often apply the `.gp` class) and find prompts are now copied, explicitly configure `copybutton_prompt_text` with a regular expression (e.g., `^\$ `) to exclude them, ensuring `copybutton_prompt_is_regexp = True`.

Install

pip install sphinx-copybutton Install `sphinx-copybutton`

Imports

sphinx_copybutton
```
# In conf.py
extensions = [
    'sphinx_copybutton'
]
```
Sphinx extensions are activated by adding their string name to the 'extensions' list in your Sphinx project's conf.py file, not via Python import statements.

Quickstart

To enable sphinx-copybutton, first install it using pip. Then, add 'sphinx_copybutton' to the `extensions` list within your Sphinx project's `conf.py` file. You can optionally configure its behavior, for example, by setting `copybutton_prompt_text` to exclude shell prompts from being copied.

# 1. Install the package:
# pip install sphinx-copybutton

# 2. Add 'sphinx_copybutton' to your conf.py extensions list:

# conf.py
import os
import sys

project = 'My Project'
copyright = '2023, Author'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx_copybutton'
]

# Optional: Configure prompt text for copy button (example)
copybutton_prompt_text = "$ "
copybutton_prompt_is_regexp = False

view raw JSON →