documentation improvements for copying functionality

doc/conf.py

@@ -98,7 +98,8 @@
 # html_sidebars = {}
 
 # CopyButton configuration
-# copybutton_prompt_text = ">>> "
+copybutton_prompt_text = ">>> "
+# Switches for testing but shouldn't be activated in the live docs
 # copybutton_only_copy_prompt_lines = False
 # copybutton_remove_prompts = False
 # copybutton_image_path = "test/TEST_COPYBUTTON.png"

doc/index.rst

@@ -26,11 +26,20 @@ And here's a code block, note the copy button to the right!
 
    copy me!
 
-By default, ``sphinx-copybutton`` will remove Python prompts from
-each line that begins with them. If it finds lines that start with the
-prompt text, all *other* lines will not be copied.
-For example, try copying the text
-below:
+
+If the code block overlaps to the right of the text area, you can just click
+the button to get the whole thing.
+
+.. code-block:: bash
+
+   123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789
+
+You can configure ``sphinx-copybutton`` to detect *input prompts* in code
+cells, and then both remove these prompts before copying, as well as skip
+lines that *don't* start with prompts (in case they are output lines).
+
+For example, this site has been configured to strip Python prompts (">>> ").
+Try copy-pasting the code block below.
 
 .. code-block:: python
 
@@ -42,16 +51,6 @@ below:
    >>> print(b)
    wow
 
-The text that ``sphinx-copybutton`` uses can be configured as well. See
-:ref:`configure_copy_text` for more information.
-
-If the code block overlaps to the right of the text area, you can just click
-the button to get the whole thing.
-
-.. code-block:: bash
-
-   123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789
-
 Installation
 ============