Adding Copy Buttons to Your Sphinx Documentation

Introduction to the Copy Button

Have you ever wished you could easily copy code blocks directly from your Sphinx-generated documentation? The sphinx-copybutton extension makes this a reality. By adding a small button to each code block, you can effortlessly copy the code to your clipboard.

This is a fantastic way to enhance user experience and make your documentation more user-friendly as it allows readers to quickly copy code snippets for testing or reference. In this article, we’ll show you how to add copy buttons to your Sphinx documentation using the sphinx-copybutton extension.

• Improved User Experience: Makes it easier for users to interact with your documentation and experiment with the code.

• Increased Efficiency: Saves time for users by eliminating the need to manually copy and paste code.

• Enhanced Accessibility: Makes your documentation more accessible to users with disabilities who may have difficulty copying code.

Installation of the extension

First install the extension using pip:

Install the sphinx-copybutton extension

pip install sphinx-copybutton

Enable the extension by adding the following line to your conf.py file:

Enable the sphinx-copybutton extension

extensions = [
    # ... other extensions
    "sphinx_copybutton",
]

Don’t forget to rebuild your documentation after making these changes and to see the copy buttons in action. But also to add the dependencies to your requirements.txt file:

Add the sphinx-copybutton extension to your requirements.txt file

sphinx-copybutton==0.5.3

Or to the pyproject.toml file:

Add the sphinx-copybutton extension to your pyproject.toml file

[build-system]
requires = ["sphinx-copybutton==0.5.3"]

Optional Configuration

You can customize the appearance and behavior of the copy buttons using the following configuration options in your conf.py file:

Customize the sphinx-copybutton extension

copybutton_prompt_text = r">>> |\.\.\. "  # Customize the prompt text
copybutton_prompt_is_regexp = True  # Treat the prompt as a regular expression
copybutton_only_copy_code_blocks = False  # Copy all code blocks, not just those with prompts
copybutton_remove_prompts = True  # Remove prompts from copied code
copybutton_trim_trailing_whitespace = True  # Trim trailing whitespace from code blocks

These options allow you to tailor the behavior of the copy buttons to suit your specific needs and preferences, and a full list of available configuration options can be found in the sphinx-copybutton documentation.

Styling the Copy Button

You can customize the appearance of the copy button using CSS. Here’s an example of how you can style the button:

Style the copy button

.copybutton {
    background-color: #f0f0f0;
    color: #333;
    border: 1px solid #ccc;
    border-radius: 3px;
    padding: 2px 5px;
    font-size: 0.8em;
    cursor: pointer;
}

.copybutton:hover {
    background-color: #e0e0e0;
}

.copybutton::after {
    content: "Copy";
}

.copybutton.copied::after {
    content: "Copied!";
}

You can add this CSS to your Sphinx theme or use a custom CSS file to apply the styles to the copy buttons.

Conclusion

Adding copy buttons to your Sphinx documentation is a simple and effective way to enhance the user experience and make your documentation more user-friendly. By allowing users to easily copy code snippets, you can improve accessibility and efficiency, making it easier for readers to interact with your documentation. The sphinx-copybutton extension provides a convenient solution for adding copy buttons to your Sphinx documentation, and with a few simple steps, you can enhance your documentation and provide a better experience for your users.