How to add a copy button in the code blocks for RST/Read the Docs

Question

I have been working on a personal "how-to" guide, chronicling and keeping a journal of my studies as I go along.

I now have a, almost too long block of code that, when I've encountered this length of code myself, its always frustrating trying to highlight JUST the block without it highlighting the whole page, or not enough.

So, my question is, for rst (reStructuredText) .. code-block::'s, is there an add-on or a way to add in a copy button, for automatic highlighting or automatically adding the text to the users clipboard? Or would this be a more html-literal type of code I'd have to include in the build and reference it in the code block? If so, what would something like that look like as well?

Fideicommissum

Answer 1

There is a dedicated package for that called sphinx-copybutton.

It's straightforward to use.

# Install
pip install sphinx-copybutton
# Declare it in the conf.py
extensions = [
    ...
    'sphinx_copybutton'
    ...
]

And that's it, generate the doc and a copy button will appear automatically in each code block.

Crazyweed

I like your answer better than mine!! Thanks @Crazyweed – Chibchan

Answer 2

In Sphinx projects, the presentation of the HTML page is controlled using a template language (Jinja2 by default). So you can make your pages more interactive by adding Javascript to the HTML template file(s) and it will get inserted when Sphinx uses that particular template file to render a page.

Locate your templates directory by searching for templates_path in your conf.py

Jinja templates can extend one another, so you probably want the file that begins with {% extends "basic/layout.html" %}.

Once you track down where in the sequence of extension you want to make your change, you need to combine:

• The section of the page where you want this to take effect (typically the main block)
• the CSS with a class for code blocks (eg. in mine it's class=highlight). The .CSS file might well be in docs/source/_static/
• A javascript snippet to create the button and write to the clipboard (eg. https://clipboardjs.com/)

Next, build the Sphinx project locally (make html) until you have it dialed in and then push your source repo to readthedocs.

Chibchan

So, this gets me part of the way there, but I seem to just be getting lost in the weeds on exactly how to place the code for my project, and part of it is my fault for not being clear on the theme I'm using... I'm hosting it both on my raspberry pi and on RTD (read the docs) and using their theme... So, how can I take that theme (which its files aren't normally included right in the docs local files) and extend that out? – Fideicommissum

@Fideicommissum you could pip install sphinx-rtd-theme into your local project... then any adjustments you make will override the defaulyt settings in RTD. I'm sorry that this isn't more straightforward. I wish I could suggest a simple way to do this, but it seems like everyone has a different approach. – Chibchan