docs: add a "Copy Commands" button for shell-session snippets

[qmonnet]

Add a Copy Commands to some code blocks. This new button attempts to copy only commands (and not their output) to the clipboard. The distinction between commands and output relies on the presence of a prompt symbol, either $ or #, at the beginning of the commands. If a command ends with a trailing backslash, copy the next line as well.

For example, the following snippet:

.. code-block:: shell-session

    $ ls -l
    foo
    cat
    $ echo 1 \
    2 \
            3\
        4
    $nospace
    # exit

should place the following text into the clipboard:

ls -l
echo 1
2
        3
    4
exit

The button is added for the following blocks, when they contain several lines and at least one command is found in the block:

• code-block, but with language shell-session only,
• Literal blocks (::),
• Parsed literals.

If accepted, this PR would mean that we should favour using prompt symbols ($/#) at the beginning of commands in snippet in the documentation, when a block contains both commands and output, to help with copy.

Waves hands and speaks in a Jedi voice: “You did NOT see me write JavaScript”

[nbusseneau]

🚀

[joestringer]

The DCO may foil your attempts at Jedi mindtrickery ;)

I can ack this. I'm OK with the idea and I understand that you've done some manual validation so it's not expected to break anything. I can't review the javascript; it looks reasonable enough at a glance but I'm not at all familiar with the language.

[qmonnet]

Here's a patch to apply on top of the PR if you want to play with it a little bit.

Playing with code snippets

diff --git a/Documentation/index.rst b/Documentation/index.rst
index e3e40bfbbdad..dbde908978bb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -7,6 +7,103 @@
 Welcome to Cilium's documentation!
 ==================================
 
+Parsed literals
+
+.. parsed-literal::
+
+   foo
+   bar
+   baz
+
+.. parsed-literal::
+
+   foo
+   bar
+   $ baz
+
+.. parsed-literal::
+
+   $ foo
+   $ bar
+   baz
+
+Literal blocks
+
+::
+
+   foo
+   bar
+   baz
+
+::
+
+   foo
+   bar
+   $ baz
+
+::
+
+   $ foo
+   $ bar
+   baz
+
+Code blocks (yaml)
+
+.. code-block:: yaml
+
+   foo:
+   - bar
+   - baz
+
+.. code-block:: yaml
+
+   foo:
+   - bar
+   $ baz
+
+.. code-block:: yaml
+
+   $ foo
+   $ bar
+   baz
+
+Code blocks (shell-session)
+
+.. code-block:: shell-session
+
+   foo:
+   - bar
+   - baz
+
+.. code-block:: shell-session
+
+   foo:
+   - bar
+   $ baz
+
+.. code-block:: shell-session
+
+   $ foo
+   $ bar
+   baz
+
+.. code-block:: shell-session
+
+   $ ls -l
+   foo
+   cat
+   $ echo 1 \
+   2 \
+           3\
+       4
+   $nospace
+     $   foobar
+     # baz \  
+       budo \
+       pouet
+   # exit
+
+
 The documentation is divided into the following sections:
 
 * :ref:`gs_guide`: Provides a simple tutorial for running a small Cilium

[qmonnet]

Based on reviews and feedback from Slack (and Documentation test passing), I'm marking as ready-to-merge.

[nbusseneau]

@qmonnet I propose we backport this to 1.10, in case we backport other PRs that rely on the new system.

[qmonnet]

Make sense to me. I'll mark for 1.8/1.9 too. I don't expect many conflicts on that button anyway :)