Add support for sphinx-copybutton

changes/1897.doc.rst

@@ -0,0 +1 @@
+All code blocks were updated to add a button to copy the relevant contents on to the user's clipboard.

core/setup.cfg

@@ -80,6 +80,7 @@ docs =
     sphinx-autobuild == 2021.3.14
     sphinx-autodoc-typehints == 1.22
     sphinx-csv-filter == 0.4.1
+    sphinx-copybutton == 0.5.2
     sphinxcontrib-spelling == 7.7.0
 
 [options.package_data]

docs/conf.py

@@ -33,6 +33,7 @@
     "sphinx_autodoc_typehints",
     "sphinx_tabs.tabs",
     "crate.sphinx.csv",
+    "sphinx_copybutton",
     "sphinx.ext.intersphinx",
 ]
 # Add any paths that contain templates here, relative to this directory.
@@ -111,9 +112,43 @@
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 # -- Options for link checking -------------------------------------------------
+
 # GitHub generates anchors in javascript
 linkcheck_ignore = [r"https://github.com/.*#"]
 
+# -- Options for copy button ---------------------------------------------------
+
+# virtual env prefix: (venv), (beeware-venv)
+venv = r"\((?:beeware-)?venv\)"
+# macOS and Linux shell prompt: $, #
+shell = r"\$|#"
+# win CMD prompt: C:\>, C:\...>
+cmd = r"C:\\>|C:\\\.\.\.>"
+# PowerShell prompt: PS C:\>, PS C:\...>
+ps = r"PS C:\\>|PS C:\\\.\.\.>"
+# zero or one whitespace char
+sp = r"\s?"
+
+# optional venv prefix
+venv_prefix = rf"(?:{venv})?"
+# one of the platforms' shell prompts
+shell_prompt = rf"(?:{shell}|{cmd}|{ps})"
+
+copybutton_prompt_text = "|".join(
+    [
+        # Python REPL
+        # r">>>\s?", r"\.\.\.\s?",
+        # IPython and Jupyter
+        # r"In \[\d*\]:\s?", r" {5,8}:\s?", r" {2,5}\.\.\.:\s?",
+        # Shell prompt
+        rf"{venv_prefix}{sp}{shell_prompt}{sp}",
+    ]
+)
+copybutton_prompt_is_regexp = True
+copybutton_remove_prompts = True
+copybutton_only_copy_prompt_lines = True
+copybutton_copy_empty_lines = False
+
 # -- Options for HTML output ---------------------------------------------------
 
 # Theme options are theme-specific and customize the look and feel of a theme

docs/how-to/contribute-code.rst

@@ -22,14 +22,14 @@ First, ensure that you have Python 3 and pip installed. To do this, run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ python3 --version
       $ pip3 --version
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ python3 --version
       $ pip3 --version
@@ -49,14 +49,14 @@ start coding. To set up a virtual environment, run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ python3 -m venv venv
       $ source venv/bin/activate
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ python3 -m venv venv
       $ source venv/bin/activate
@@ -66,7 +66,7 @@ start coding. To set up a virtual environment, run:
     .. code-block:: doscon
 
       C:\...>python3 -m venv venv
-      C:\...>venv/Scripts/activate
+      C:\...>venv\Scripts\activate
 
 Your prompt should now have a ``(venv)`` prefix in front of it.
 
@@ -80,19 +80,29 @@ Next, install any additional dependencies for your operating system:
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    Ubuntu 18.04+, Debian 10+
+
+    .. code-block:: console
 
-      # Ubuntu 18.04+, Debian 10+
       (venv) $ sudo apt-get update
       (venv) $ sudo apt-get install python3-dev libgirepository1.0-dev libcairo2-dev libpango1.0-dev libwebkit2gtk-4.0-37 gir1.2-webkit2-4.0
 
-      # Fedora
+    Fedora
+
+    .. code-block:: console
+
       (venv) $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-devel cairo-gobject-devel pango-devel webkitgtk3
 
-      # Arch / Manjaro
+    Arch / Manjaro
+
+    .. code-block:: console
+
       (venv) $ sudo pacman -Syu git pkgconf cairo python-cairo pango gobject-introspection gobject-introspection-runtime python-gobject webkit2gtk
 
-      # FreeBSD
+    FreeBSD
+
+    .. code-block:: console
+
       (venv) $ sudo pkg update
       (venv) $ sudo pkg install gtk3 pango gobject-introspection cairo webkit2-gtk3
 
@@ -144,14 +154,14 @@ source packages, so we have to manually install each package:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ cd toga
       (venv) $ pip install -e "./core[dev]" -e ./dummy -e ./cocoa
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ cd toga
       (venv) $ pip install -e ./core[dev] -e ./dummy -e ./gtk
@@ -172,14 +182,14 @@ git commit. To enable pre-commit, run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ pre-commit install
       pre-commit installed at .git/hooks/pre-commit
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ pre-commit install
       pre-commit installed at .git/hooks/pre-commit
@@ -199,7 +209,7 @@ pre-commit will make the changes needed to correct the problems it has found:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git add some/interesting_file.py
       (venv) $ git commit -m "Minor change"
@@ -225,7 +235,7 @@ pre-commit will make the changes needed to correct the problems it has found:
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git add some/interesting_file.py
       (venv) $ git commit -m "Minor change"
@@ -282,7 +292,7 @@ and re-commit the change.
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git add some/interesting_file.py
       (venv) $ git commit -m "Minor change"
@@ -302,7 +312,7 @@ and re-commit the change.
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git add some/interesting_file.py
       (venv) $ git commit -m "Minor change"
@@ -538,13 +548,13 @@ To run the core test suite:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py-core
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py-core
 
@@ -616,13 +626,13 @@ specific test, using `pytest specifiers
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py-core -- tests/path_to_test_file/test_some_test.py
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py-core -- tests/path_to_test_file/test_some_test.py
 
@@ -655,15 +665,15 @@ test mode:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ python -m pip install briefcase
       (venv) $ cd testbed
       (venv) $ briefcase dev --test
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ python -m pip install briefcase
       (venv) $ cd testbed
@@ -694,13 +704,13 @@ So - to run *only* the button tests in slow mode, you could run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ briefcase dev --test -- tests/widgets/test_button.py --slow
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ briefcase dev --test -- tests/widgets/test_button.py --slow
 
@@ -725,21 +735,21 @@ run``.
 
     To run the Android test suite:
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ briefcase run android --test
 
     To run the iOS test suite:
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ briefcase run iOS --test
 
   .. group-tab:: Linux
 
     To run the Android test suite:
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ briefcase run android --test
 
@@ -858,13 +868,13 @@ To create a feature branch, run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git checkout -b fix-layout-bug
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ git checkout -b fix-layout-bug
 

docs/how-to/contribute-docs.rst

@@ -25,14 +25,14 @@ You'll also need to install the Enchant spell checking library.
 
     Enchant can be installed using `Homebrew <https://brew.sh>`__:
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ brew install enchant
 
     If you're on an M1 machine, you'll also need to manually set the location
     of the Enchant library:
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib
 
@@ -73,19 +73,19 @@ Once your development environment is set up, run:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs
 
   .. group-tab:: Windows
 
-    .. code-block:: powershell
+    .. code-block:: doscon
 
       (venv) C:\...>tox -e docs
 
@@ -102,13 +102,13 @@ additional "lint" checks. To run the lint checks:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs-lint
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs-lint
 
@@ -143,19 +143,19 @@ To force a rebuild for all of the documentation:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs-all
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e docs-all
 
   .. group-tab:: Windows
 
-    .. code-block:: powershell
+    .. code-block:: doscon
 
       (venv) C:\...>tox -e docs-all