Merge branch 'master' into master

Author: choldgraf

.github/workflows/integration.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python 3.7
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: 3.7
     - name: Install dependencies
@@ -35,7 +35,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v2
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm ci
@@ -48,12 +48,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -78,7 +78,7 @@ jobs:
       - name: Checkout source
         uses: actions/checkout@v2
       - name: Set up Python 3.7
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v2
         with:
           python-version: 3.7
       - name: Build package
@@ -87,7 +87,7 @@ jobs:
           git submodule update --init
           python setup.py sdist bdist_wheel
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@v1.1.0
+        uses: pypa/gh-action-pypi-publish@v1.4.2
         with:
           user: __token__
           password: ${{ secrets.PYPI_KEY }}

.gitignore

@@ -112,3 +112,5 @@ _build/
 node_modules/
 
 .DS_Store
+
+.idea

.pre-commit-config.yaml

@@ -8,16 +8,20 @@ exclude: >
 
 repos:
 
-  - repo: git://github.com/pre-commit/pre-commit-hooks
-    rev: v2.2.3
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
     hooks:
     - id: check-json
     - id: check-yaml
     - id: end-of-file-fixer
     - id: trailing-whitespace
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 3.9.2
+    hooks:
     - id: flake8
 
   - repo: https://github.com/psf/black
-    rev: stable
+    rev: 21.5b1
     hooks:
     - id: black

doc/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -101,6 +100,8 @@
 # CopyButton configuration
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
 copybutton_prompt_is_regexp = True
+copybutton_line_continuation_character = "\\"
+copybutton_here_doc_delimiter = "EOT"
 # Switches for testing but shouldn't be activated in the live docs
 # copybutton_only_copy_prompt_lines = False
 # copybutton_remove_prompts = False

doc/index.rst

@@ -60,7 +60,7 @@ Installation
 
 .. note::
 
-   ``sphinx-copybutton`` only works on Python >= 3.4
+   ``sphinx-copybutton`` only works on Python >= 3.6
 
 You can install ``sphinx-copybutton`` with ``pip``:
 
@@ -268,6 +268,80 @@ strip the prompts), use the following configuration in ``conf.py``:
 
     copybutton_remove_prompts = False
 
+Configure whether *empty* lines are copied
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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``:
+
+.. code-block:: python
+
+    copybutton_copy_empty_lines = False
+
+Honor line continuation characters when copying multline-snippets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you may wish to copy a code block like this one:
+
+.. code-block:: bash
+
+    $ 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:
+
+.. code-block:: python
+
+    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 multline-snippets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`HERE-documents <https://en.wikipedia.org/wiki/Here_document>`_ are a form of multiline string literals
+in which line breaks and other whitespace (including indentation) is preserved.
+For example:
+
+.. code-block:: bash
+
+    $ 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:
+
+.. code-block:: python
+
+   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.
+
 Use a different copy button image
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~