Use and customize#
This section describes major ways to use and control sphinx-copybutton’s behavior.
Automatic exclusion of prompts from the copies#
The Sphinx code highlighter, Pygments, tags the prompts (>>>, ...,
In [1]:, $) of console sessions.
Sphinx by default excludes prompts from being selectable.
However, by default sphinx-copybutton will copy these prompts (for backwards compatibility with the other “manually-selectable exclude” options).
To make sphinx-copybutton skip all prompt characters generated by pygments, use the following setting:
copybutton_exclude = '.linenos, .gp'
To skip all console outputs, add .go to the string above.
For automatic exclusion, make sure to use the right highlight language.
For example: pythonconsole instead of python, console instead of bash,
ipythonconsole instead of ipython, etc.
This setting can also be used to exclude arbitrary css classes from
being copied. By default .linenos are excluded. .linenos is the
Sphinx default for line numbers, .gp is the Pygments class for the
prompts, and .go is the class for console outputs.
This setting conflicts with most of pattern-based copy-selection settings below, so should not be used with them. This will hopefully be improved in the future.
Strip and configure input prompts for code cells#
By default, sphinx-copybutton will copy the entire contents of a code
block when the button is clicked. For many languages, it is common to
include input prompts with your examples, along with the outputs from
running the code.
sphinx-copybutton provides functionality to both
strip input prompts, as well as only select lines that begin with a prompt.
This allows users to click the button and only copy the input text,
excluding the prompts and outputs.
To define the prompt text that you’d like removed from copied text in your code
blocks, use the following configuration value in your conf.py file:
copybutton_prompt_text = "myinputprompt"
When this variable is set, sphinx-copybutton will remove the prompt from
the beginning of any lines that start with the text you specify. In
addition, only the lines that contain prompts will be copied if any are
discovered. If no lines with prompts are found, then the full contents of
the cell will be copied.
For example, to exclude traditional Python prompts from your copied code, use the following configuration:
copybutton_prompt_text = ">>> "
Using regexp prompt identifiers#
If your prompts are more complex than a single string, then you can use a regexp to match with.
Note
Keep in mind that the RegExp you are writing is evaluated in JavaScript and not in Python. In some edge cases this might lead to different results.
If you enclose your regexp in a raw string (r""),
you can easily test that your RegExp matches all the wanted prompts,
i.e. at RegEx101.
For example this documentation uses the following configuration:
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
Which matches the following prompts and their continuations if they exist:
Prompt Name |
RegEx Pattern |
Matched String Examples |
|---|---|---|
Python Repl + continuation |
|
|
Bash |
|
|
|
|
|
|
|
|
An example usage would be the ipython-directive:
``ipython`` and ``qtconsole`` style:
.. code-block:: ipython
In [1]: first
...: continuation
output
In [2]: second
``jupyter`` style:
.. code-block:: ipython
In [1]: first
: continuation
output
In [2]: second
ipython and qtconsole style:
In [1]: first
...: continuation
output
In [2]: second
jupyter style:
In [1]: first
: continuation
output
In [2]: second
If you want a detailed explanation how the RegEx’s work you can also use RegEx101 and read the Explanation sidebar.
Configure whether only lines with prompts are copied#
By default, if sphinx-copybutton detects lines that begin with code prompts, it will only copy the text in those lines (after stripping the prompts). This assumes that the rest of the code block contains outputs that shouldn’t be copied.
To disable this behavior, use the following configuration in conf.py:
copybutton_only_copy_prompt_lines = False
In this case, all lines of the code blocks will be copied after the prompts are stripped.
Configure whether the input prompts should be stripped#
By default, sphinx-copybutton will remove the prompt text from lines
according to the value of copybutton_prompt_text.
To disable this behavior and copy the full text of lines with prompts
(for example, if you’d like to copy only the lines with prompts, but not
strip the prompts), use the following configuration in conf.py:
copybutton_remove_prompts = False
Keep empty lines#
By default, sphinx-copybutton will also copy / pass through empty lines,
determined by line.trim() === ''.
To disable copying empty lines, use the following configuration in conf.py:
copybutton_copy_empty_lines = False
Multi-line snippets#
Multi-line snippets are single commands that continue across multiple lines (usually to save horizontal space).
sphinx-copybutton tries to copy this text with the expectation that you’ll want to past the text as a single line in some other application.
See below for how to control this.
Honor line continuation characters when copying multline-snippets#
Sometimes you may wish to copy a code block like this one:
$ datalad download-url http://www.tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf \
--dataset . \
-m "add beginners guide on bash" \
-O books/bash_guide.pdf
Assuming that you specified $ as your prompt, sphinx-copybutton will only copy
the first line by default.
To copy all lines above, you can use the following configuration:
copybutton_line_continuation_character = "\\"
Note that if we want to define \ as the line continuation character, we have to “escape”
it with another \, as with any Python string that should carry a literal \.
Next, this configuration will make the code look for lines to copy based on the rules above, but if one of the lines to be copied contains a line continuation character, then the next line will be automatically copied, regardless of whether it matches the other rules.
Honor HERE-document syntax when copying multiline-snippets#
HERE-documents are a form of multiline string literals in which line breaks and other whitespace (including indentation) is preserved. For example:
$ cat << EOT > notes.txt
This is an example sentence.
Put some indentation on this line.
EOT
Executing this codeblock in the terminal will create a file notes.txt with the exact
text from line two of the codeblock until (but not including) the final line containing EOT.
However, assuming that you specified $ as your prompt, sphinx-copybutton will only copy
the first line by default.
sphinx-copybutton can be configured to copy the whole “HERE-document” by using the following configuration:
copybutton_here_doc_delimiter = "EOT"
This will continue to look for lines to copy based on the rules above,
but if one of the lines to be copied contains the defined delimiter (here: EOT),
then all following lines will be copied literally until the next delimiter is
encountered in a line.