当前位置：文江博客话题详情

Sphinx、reStructuredText 显示/隐藏代码片段

发布于 2024-08-25 12:01:51 字数 368 浏览 9 评论 0 原文

我一直在使用 Sphinx 和 reStructuredText。

在我的文档中，有一些很长的代码片段。我希望能够将它们默认隐藏，并使用一个小“显示/隐藏”按钮来展开它们（示例）。

有没有标准的方法来做到这一点？

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

枕头说它不想醒 2024-09-01 12:01:51

您不需要自定义主题。使用内置指令 container，它允许您将自定义 css 类添加到块并覆盖现有主题以添加一些 javascript 来添加显示/隐藏功能。

这是_templates/page.html：

{% extends "!page.html" %}

{% block footer %}
 <script type="text/javascript">
    $(document).ready(function() {
        $(".toggle > *").hide();
        $(".toggle .header").show();
        $(".toggle .header").click(function() {
            $(this).parent().children().not(".header").toggle(400);
            $(this).parent().children(".header").toggleClass("open");
        })
    });
</script>
{% endblock %}

这是_static/custom.css：

.toggle .header {
    display: block;
    clear: both;
}

.toggle .header:after {
    content: " ▶";
}

.toggle .header.open:after {
    content: " ▼";
}

这已添加到conf.py：

def setup(app):
    app.add_css_file('custom.css')

现在您可以显示/隐藏一段代码。

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: xml
       :linenos:

       from plone import api
       ...

我在这里使用非常相似的东西进行练习：https://training.plone。 org/5/mastering-plone/about_mastering.html#exercises

You don't need a custom theme. Use the built-in directive container that allows you to add custom css-classes to blocks and override the existsting theme to add some javascript to add the show/hide-functionality.

This is _templates/page.html:

{% extends "!page.html" %}

{% block footer %}
 <script type="text/javascript">
    $(document).ready(function() {
        $(".toggle > *").hide();
        $(".toggle .header").show();
        $(".toggle .header").click(function() {
            $(this).parent().children().not(".header").toggle(400);
            $(this).parent().children(".header").toggleClass("open");
        })
    });
</script>
{% endblock %}

This is _static/custom.css:

.toggle .header {
    display: block;
    clear: both;
}

.toggle .header:after {
    content: " ▶";
}

.toggle .header.open:after {
    content: " ▼";
}

This is added to conf.py:

def setup(app):
    app.add_css_file('custom.css')

Now you can show/hide a block of code.

.. container:: toggle

    .. container:: header

        **Show/Hide Code**

    .. code-block:: xml
       :linenos:

       from plone import api
       ...

I use something very similar for exercises here: https://training.plone.org/5/mastering-plone/about_mastering.html#exercises

回复收藏 0 原文

疯狂的代价 2024-09-01 12:01:51

您可以使用内置的 HTML 可折叠 details 标记将代码包装在两个原始 HTML 指令中

.. raw:: html

   <details>
   <summary><a>big code</a></summary>

.. code-block:: python

   lots_of_code = "this text block"

.. raw:: html

   </details>

生成：

<details>
<summary><a>big code</a></summary>
<pre>lots_of_code = "this text block"</pre>
</details>

You can use the built-in HTML collapsible details tag by wrapping the code in two raw HTML directives

.. raw:: html

   <details>
   <summary><a>big code</a></summary>

.. code-block:: python

   lots_of_code = "this text block"

.. raw:: html

   </details>

Produces:

<details>
<summary><a>big code</a></summary>
<pre>lots_of_code = "this text block"</pre>
</details>

回复收藏 0 原文

断肠人 2024-09-01 12:01:51

有一个非常简单的扩展提供了该功能：https://github.com/scopatz/hiddencode

对我来说效果很好。

回复收藏 0 原文

百善笑为先 2024-09-01 12:01:51

我认为最简单的方法是创建一个自定义 Sphinx 主题，在其中告诉某些 html 元素具有此功能。一点 JQuery 在这里会有很大帮助。

但是，如果您希望能够在 reStructuredText 标记中指定这一点，那么您需要

将这样的东西包含在 Sphinx 本身中，或者
在 Sphinx/docutils 扩展中实现它......然后创建一个知道的 Sphinx 主题这个功能。

这会需要更多的工作，但会给你更多的灵活性。

回复收藏 0 原文

北方的巷 2024-09-01 12:01:51

云 sphinx 主题具有提供可切换部分的自定义指令 html-toggle。引用他们的网页：

您可以使用 .. rst-class:: html-toggle 标记部分，这将使该部分默认折叠在 html 下，并在右侧显示“显示部分”切换链接标题。

这里是他们的测试演示页面的链接。

回复收藏 0 原文

执笏见 2024-09-01 12:01:51

sphinx-togglebutton

看起来已经制作了一个新的 sphinx 扩展既然这个问题已经得到解答，就这样做吧。

运行： pip install sphinx-togglebutton

添加到 conf.py

extensions = [
...
'sphinx_togglebutton'
...
]

第一个源文件中：

.. admonition:: Show/Hide
  :class: dropdown

  hidden message

sphinx-togglebutton

Looks like a new sphinx extension has been made to do just this since this question has been answered.

Run: pip install sphinx-togglebutton

Add to conf.py

extensions = [
...
'sphinx_togglebutton'
...
]

In rst source file:

.. admonition:: Show/Hide
  :class: dropdown

  hidden message

回复收藏 0 原文

将军与妓 2024-09-01 12:01:51

由于上述方法似乎都不适合我，因此我最终解决了这个问题：

在源目录中创建一个包含以下内容的文件substitutions.rst：

<前><代码>.. |toggleStart|原始:: html

<详情>
<总结>折叠块的标题

.. |切换结束|原始:: html

>
在要使用的每个文件的开头添加以下行添加可折叠块

<前><代码>..include::替换.rst
现在，只需使用即可使部分代码可折叠：

<前><代码>|toggleStart|

您想要折叠的文本
..代码块:: python
x=1

|切换结束|

since none of the above methods seem to work for me, here's how I solved it in the end:

create a file substitutions.rst in your source-directory with the following content:

.. |toggleStart| raw:: html

   <details>
   <summary><a> the title of the collapse-block </a></summary>

.. |toggleEnd| raw:: html

   </details>
   <br/>

add the following line at the beginning of every file you want to use add collapsible blocks
```
..include:: substitutions.rst
```

now, to make a part of the code collapsible simply use:

|toggleStart|

the text you want to collapse
..code-block:: python 
    x=1

|toggleEnd|

回复收藏 0 原文

情魔剑神 2024-09-01 12:01:51

另一种选择是 sphinx-design 扩展中的下拉指令。从文档中：

安装 sphinx-design

pip install sphinx-design

将扩展添加到 extensions 列表中的 conf.py

extensions = ["sphinx_design"]

在第一个文件中使用 dropdown 指令：

.. dropdown::

    Dropdown content

Another option is the dropdown directive in the sphinx-design extension. From the docs:

Install sphinx-design

pip install sphinx-design

Add the extension to conf.py in the extensions list

extensions = ["sphinx_design"]

Use the dropdown directive in your rst file:

.. dropdown::

    Dropdown content

回复收藏 0 原文

甜心 2024-09-01 12:01:51

TL;DR

您可以使用 jsphinx 来实现此目的。检查演示/示例。

它适用于 literalinclude：演示/示例。
它适用于代码块：demo/示例。

文档中对方法进行了很好的解释。

相对于现有解决方案的优势：

您的代码段始终是完整的。你可以测试它们。
它是一个 JavaScript 库。它为您现有的文档增加了非常小的占用空间。

回复收藏 0 原文

违心° 2024-09-01 12:01:51

自版本 0.20 (2023-05-09) 起，Docutils HTML5 编写器支持详细披露元素。

.. rst-class:: details

big code block's caption
    .. code:: python

        lots_of_code = "this text block"

产生

<div class="details">
<details>
<summary>big code block’s caption</summary>
<pre class="code literal-block"><code>lots_of_code = "this text block"</code></pre>
</details>
</div>

Since version 0.20 (2023-05-09), the Docutils HTML5 writer supports details disclosure elements.

.. rst-class:: details

big code block's caption
    .. code:: python

        lots_of_code = "this text block"

produces

<div class="details">
<details>
<summary>big code block’s caption</summary>
<pre class="code literal-block"><code>lots_of_code = "this text block"</code></pre>
</details>
</div>

回复收藏 0 原文

~没有更多了~