Merge pull request #1213 from rmartin16/copybutton

Add support for `sphinx-copybutton`

changes/1213.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.

docs/background/faq.rst

@@ -39,7 +39,7 @@ with Briefcase by testing for the existence of the ``Briefcase-Version`` tag::
 Can I use third-party Python packages in my app?
 ------------------------------------------------
 
-Yes! Briefcase uses `pip` to install third-party packages into your app bundle.
+Yes! Briefcase uses ``pip`` to install third-party packages into your app bundle.
 As long as the package is available on PyPI, or you can provide a wheel file for
 the package, it can be added to the ``requires`` declaration in your
 ``pyproject.toml`` file and used by your app at runtime.

docs/conf.py

@@ -30,6 +30,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx_tabs.tabs",
+    "sphinx_copybutton",
     "sphinx.ext.intersphinx",
 ]
 
@@ -97,12 +98,46 @@
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 # -- Options for link checking -------------------------------------------------
+
 linkcheck_anchors_ignore = [
     # Ignore anchor detection/verification for Apple help links
     # e.g.: https://help.apple.com/xcode/mac/current/#/dev97211aeac
     "^/dev[0-9a-f]{9}$"
 ]
 
+# -- Options for copy button ---------------------------------------------------
+
+# virtual env prefix: (venv), (beeware-venv), (testenv)
+venv = r"\((?:(?:beeware-)?venv|testvenv)\)"
+# 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/access-packaging-metadata.rst

@@ -54,7 +54,7 @@ in your app's ``pyproject.toml`` configuration:
   * **Author** - ``author``
   * **Author-email** - ``author_email``
 
-For example, the metadata for the app constructed by the `Beeware Tutorial
+For example, the metadata for the app constructed by the `BeeWare Tutorial
 <https://docs.beeware.org/en/latest/tutorial/tutorial-1.html>`_ would
 contain::
 

docs/how-to/code-signing/android.rst

@@ -45,32 +45,31 @@ Google Play.
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ mkdir -p ~/.android
       $ ~/Library/Caches/org.beeware.briefcase/tools/java/Contents/Home/bin/keytool -keyalg RSA -deststoretype pkcs12 -genkey -v -storepass android -keystore ~/.android/upload-key-helloworld.jks -keysize 2048 -dname "cn=Upload Key" -alias upload-key -validity 10000
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ mkdir -p ~/.android
       $ ~/.cache/briefcase/tools/java/bin/keytool -keyalg RSA -deststoretype pkcs12 -genkey -v -storepass android -keystore ~/.android/upload-key-helloworld.jks -keysize 2048 -dname "cn=Upload Key" -alias upload-key -validity 10000
 
-  .. group-tab:: Windows (PowerShell)
-
-    .. code-block:: powershell
-
-      C:\...>If (-Not (Test-Path "$env:HOMEPATH/.android")) { New-Item -Path "$env:HOMEPATH\.android" -ItemType Directory }
-      C:\...>& "$env:LOCALAPPDATA\BeeWare\briefcase\Cache\tools\java\bin\keytool.exe" -keyalg RSA -deststoretype pkcs12 -genkey -v -storepass android -keystore "$env:HOMEPATH\.android\upload-key-helloworld.jks" -keysize 2048 -dname "cn=Upload Key" -alias upload-key -validity 10000
-
   .. group-tab:: Windows (cmd)
 
     .. code-block:: doscon
 
       C:\...>IF not exist %HOMEPATH%\.android mkdir %HOMEPATH%\.android
       C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\keytool.exe -keyalg RSA -deststoretype pkcs12 -genkey -v -storepass android -keystore %HOMEPATH%\.android\upload-key-helloworld.jks -keysize 2048 -dname "cn=Upload Key" -alias upload-key -validity 10000
 
+  .. group-tab:: Windows (PowerShell)
+
+    .. code-block:: pwsh-session
+
+      PS C:\...> If (-Not (Test-Path "$env:HOMEPATH/.android")) { New-Item -Path "$env:HOMEPATH\.android" -ItemType Directory }
+      PS C:\...> & "$env:LOCALAPPDATA\BeeWare\briefcase\Cache\tools\java\bin\keytool.exe" -keyalg RSA -deststoretype pkcs12 -genkey -v -storepass android -keystore "$env:HOMEPATH\.android\upload-key-helloworld.jks" -keysize 2048 -dname "cn=Upload Key" -alias upload-key -validity 10000
 
 This creates a 2048-bit key and stores it in a Java keystore located in the
 ``.android`` folder within your home folder. Since the key's purpose is to be

docs/how-to/code-signing/windows.rst

@@ -48,9 +48,19 @@ commands to import certificates in to one of its certificate stores.
 For instance, this will a import PFX file in to the ``Personal`` certificate
 store of ``Current User``:
 
-.. code-block:: powershell
+.. tabs::
 
-    Import-PfxCertificate -FilePath .\cert.pfx -CertStoreLocation Cert:\CurrentUser\My -Password MySecretPassword
+  .. group-tab:: CMD
+
+    .. code-block:: doscon
+
+      C:\...>certutil.exe -user -importpfx -p MySecretPassword My .\cert.pfx
+
+  .. group-tab:: PowerShell
+
+    .. code-block:: pwsh-session
+
+      PS C:\...> Import-PfxCertificate -FilePath .\cert.pfx -CertStoreLocation Cert:\CurrentUser\My -Password MySecretPassword
 
 Refer to your Certificate Authority's documentation for specific instructions.
 
@@ -68,6 +78,6 @@ to, double-click it to access information about it. Near the bottom of the list
 on the Details tab, you'll find the ``Thumbprint`` field with the 40 character
 SHA-1 hash to use as the ``identity`` in the Briefcase package command.
 
-.. code-block:: powershell
+.. code-block:: doscon
 
-    briefcase package --identity <certificate thumbprint>
+    (venv) C:\...>briefcase package --identity <certificate thumbprint>

docs/how-to/contribute-code.rst

@@ -21,7 +21,7 @@ and then install the development version of Briefcase and its dependencies:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ git clone https://github.com/beeware/briefcase.git
       $ cd briefcase
@@ -31,7 +31,7 @@ and then install the development version of Briefcase and its dependencies:
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       $ git clone https://github.com/beeware/briefcase.git
       $ cd briefcase
@@ -58,14 +58,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
@@ -85,7 +85,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"
@@ -111,7 +111,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"
@@ -168,7 +168,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"
@@ -188,7 +188,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"
@@ -232,13 +232,13 @@ process. To set up a testing environment and run the full test suite:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox
 
@@ -257,19 +257,19 @@ the process while developing, you can run the tests on one Python version only:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py
 
   .. group-tab:: Windows
 
-    .. code-block:: bash
+    .. code-block:: doscon
 
       (venv) C:\...>tox -e py
 
@@ -279,43 +279,43 @@ Or, you can run a single test file on a single version of Python:
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
       (venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
 
   .. group-tab:: Windows
 
-    .. code-block:: bash
+    .. code-block:: doscon
 
       (venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py
 
-Or, to run using a specific version of Python, e.g. when you want to use Python 3.7:
+Or, to run using a specific version of Python, e.g. when you want to use Python 3.10:
 
 .. tabs::
 
   .. group-tab:: macOS
 
-    .. code-block:: bash
+    .. code-block:: console
 
-      (venv) $ tox -e py37
+      (venv) $ tox -e py310
 
   .. group-tab:: Linux
 
-    .. code-block:: bash
+    .. code-block:: console
 
-      (venv) $ tox -e py37
+      (venv) $ tox -e py310
 
   .. group-tab:: Windows
 
-    .. code-block:: bash
+    .. code-block:: doscon
 
-      (venv) C:\...>tox -e py37
+      (venv) C:\...>tox -e py310
 
 substituting the version number that you want to target. You can also specify
 the `towncrier-check`, `docs` or `package` targets to check release notes,

docs/how-to/contribute-docs.rst

@@ -30,14 +30,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
 
@@ -75,19 +75,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
 
@@ -104,19 +104,19 @@ documentation:
 
   .. 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
 
   .. group-tab:: Windows
 
-    .. code-block:: powershell
+    .. code-block:: doscon
 
       (venv) C:\...>tox -e docs-lint
 
@@ -139,19 +139,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