如何在 RST/阅读文档的代码块中添加复制按钮

Question

我一直在制定个人的“操作方法”指南，在我进行的过程中记录并保存我的学习日记。

我现在有一个几乎太长的代码块，当我自己遇到这么长的代码时，试图突出显示块而不突出整个页面总是令人沮丧，或者还不够。

所以，我的问题是，对于rst(reStructuredText).. code-block::的，是否有附加组件或添加copy按钮的方法，用于自动突出显示或自动将文本添加到用户剪贴板？或者这是否是我必须包含在构建中并在代码块中引用它的更多 html 文字类型的代码？如果是这样，那么类似的东西又会是什么样子？

Answer 1

有一个名为sphinx-copybutton.

使用起来很简单。

# Install
pip install sphinx-copybutton
# Declare it in the conf.py
extensions = [
    ...
    'sphinx_copybutton'
    ...
]

就是这样，生成文档并在每个代码块中自动出现一个复制按钮。

Answer 2

在Sphinx项目中，HTML页面的呈现是使用模板语言（默认为Jinja2）控制的。因此，您可以通过将 Javascript 添加到 HTML 模板文件来使页面更具交互性，并且当 Sphinx 使用该特定模板文件呈现页面时，它将被插入。

templates_path通过在您的模板中搜索来找到您的模板目录conf.py

Jinja 模板可以相互扩展，因此您可能需要以{% extends "basic/layout.html" %}.

一旦您找到了要在扩展顺序中进行更改的位置，您需要组合：

• 您希望此功能生效的页面部分（通常是主块）
• 带有代码块类的CSS（例如，在我的代码块中是class=highlight）。.CSS 文件很可能位于 docs/source/_static/ 中
• 用于创建按钮并写入剪贴板的 JavaScript 片段（例如https://clipboardjs.com/）

接下来，在本地构建 Sphinx 项目 ( make html)，直到将其拨入，然后将源存储库推送到 readthedocs。