使用与自定义#
本节描述了如何使用和控制 sphinx-copybutton 的主要方法。
自动排除副本中的提示#
Sphinx 代码高亮器 Pygments 会标记控制台会话的提示符（>>>、...、In [1]:、$）。Sphinx 默认情况下会排除提示符不可选择。然而，默认情况下 sphinx-copybutton 会复制这些提示符（为了与其他“手动选择排除”选项向后兼容）。
要使 sphinx-copybutton 跳过 Pygments 生成的所有提示符字符，请使用以下设置：
copybutton_exclude = '.linenos, .gp'
要 跳过所有控制台输出，请在上述字符串中添加 .go。
对于自动排除，请确保使用正确的高亮语言。例如：pythonconsole 而不是 python，console 而不是 bash，ipythonconsole 而不是 ipython 等。
此设置还可用于排除不希望被复制的任意 CSS 类。默认情况下排除 .linenos。.linenos 是 Sphinx 默认的行号，.gp 是提示符的 Pygments 类，.go 是控制台输出的类。
此设置与下面大多数基于模式的复制选择设置冲突，因此不应与它们一起使用。希望在未来能够改进。这一设置与下面大多数基于模式的复制选择设置冲突，因此不应与它们一起使用。希望在未来能够改进。
剥离和配置代码单元的输入提示#
默认情况下，单击按钮时 sphinx-copybutton 将复制代码块的整个内容。对于许多语言，通常在示例中包含 输入提示，以及运行代码的输出。
sphinx-copybutton 提供了剥离输入提示的功能，以及仅选择以提示符开头的行。这使用户可以单击按钮并仅复制输入文本，排除提示符和输出。这使用户可以单击按钮并仅复制输入文本，排除提示符和输出。
要定义要从代码块中复制的文本中删除的提示文本，请在 conf.py 文件中使用以下配置值：
copybutton_prompt_text = "myinputprompt"
设置此变量后，sphinx-copybutton 将从以您指定的文本开头的任何行中删除提示。此外，如果发现任何带提示的行，则仅复制包含提示的行。如果没有找到带提示的行，则将复制单元的全部内容。
例如，要从复制的代码中排除传统的 Python 提示符，请使用以下配置：
copybutton_prompt_text = ">>> "
使用正则表达式提示符标识符#
如果您的提示比单个字符串更复杂，则可以使用正则表达式进行匹配。
备注
请记住，您正在编写的 RegExp 是在 JavaScript 中进行评估的，而不是在 Python 中。在某些边缘情况下，这可能会导致不同的结果。
如果您将正则表达式括在原始字符串中（r""），则可以轻松测试您的 RegExp 是否匹配所有所需的提示，即在 [RegEx101]。
例如，此文档使用以下配置：
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
匹配以下提示及其延续（如果存在）：
提示名称 |
正则表达式模式 |
匹配的字符串示例 |
|---|---|---|
Python REPL + 延续 |
|
|
Bash |
|
|
|
|
|
|
|
|
使用 ipython-directive 的示例:
``ipython`` and ``qtconsole`` style:
.. code-block:: ipython
In [1]: first
...: continuation
output
In [2]: second
``jupyter`` style:
.. code-block:: ipython
In [1]: first
: continuation
output
In [2]: second
ipython and qtconsole style:
In [1]: first
...: continuation
output
In [2]: second
jupyter style:
In [1]: first
: continuation
output
In [2]: second
如果您想详细了解正则表达式如何工作，您可以使用 [RegEx101] 并阅读 Explanation 侧边栏。
配置是否仅复制带提示的行#
默认情况下，如果 sphinx-copybutton 检测到以代码提示符开头的行，它将仅复制这些行中的文本（在剥离提示后）。
要禁用此行为，请在 conf.py 中使用以下配置：
copybutton_only_copy_prompt_lines = False
在这种情况下，剥离提示后将复制代码块的所有行。
配置是否应剥离输入提示#
默认情况下，sphinx-copybutton 将根据 copybutton_prompt_text 的值从行中删除提示文本。
要禁用此行为并复制带提示的行的完整文本（例如，如果您只想复制带提示的行，但不剥离提示），请在 conf.py 中使用以下配置：
copybutton_remove_prompts = False
保留 空 行#
默认情况下，sphinx-copybutton 还将复制/传递空行，由 line.trim() === '' 确定。
要禁用复制空行，请在 conf.py 中使用以下配置：
copybutton_copy_empty_lines = False
多行片段#
多行片段是跨多行继续的单个命令（通常是为了节省水平空间）。sphinx-copybutton 尝试复制此文本，期望您希望将文本作为单行粘贴到其他应用程序中。有关如何控制此内容，请参见下文。
复制多行片段时遵守行继续字符#
有时您可能希望复制此代码块：
$ 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
假设您将 $ 指定为提示符，默认情况下 sphinx-copybutton 只会复制第一行。
要复制上面的所有行，可以使用以下配置：
copybutton_line_continuation_character = "\\"
请注意，如果要将 \ 定义为行继续字符，必须用另一个 \ 进行“转义”，就像任何应携带文字 \ 的 Python 字符串一样。
接下来，此配置将使代码根据上述规则查找要复制的行，但如果要复制的行中包含行继续字符，则下一行将自动复制，无论它是否符合其他规则。
复制多行片段时遵守 HERE-document 语法#
HERE-documents 是一种多行字符串文字形式，其中保留了换行符和其他空格（包括缩进）。例如：
$ cat << EOT > notes.txt
This is an example sentence.
Put some indentation on this line.
EOT
在终端中执行此代码块将创建名为 notes.txt 的文件，其中包含代码块的第二行直到（但不包括）包含 EOT 的最后一行的确切文本。
然而，假设您将 $ 指定为提示符，默认情况下 sphinx-copybutton 只会复制第一行。
sphinx-copybutton 可以通过使用以下配置来复制整个“HERE-document”：
copybutton_here_doc_delimiter = "EOT"
这将继续根据上述规则查找要复制的行，但如果要复制的行中包含定义的分隔符（此处为：EOT），则所有后续行将被逐字复制，直到在行中遇到下一个分隔符为止。