Sphinx, reStructuredText показать/скрыть фрагменты кода

Я документировал программный пакет, используя Sphinx и ReStructuredText.

В моих документах есть некоторые фрагменты кода. Я хочу, чтобы они были скрыты по умолчанию, с небольшой кнопкой "Показать/Скрыть", которая расширила бы их (Example).

Есть ли стандартный способ сделать это?

Ответ 1

Я думаю, что самый простой способ сделать это - создать пользовательскую тему Sphinx, в которой вы скажете определенным элементам html, чтобы иметь эту функциональность. Маленький JQuery проделает долгий путь здесь.

Если, однако, вы хотите указать это в своей разметке reStructuredText, вам нужно будет либо

получить такую вещь, включенную в сам Сфинкс или
реализовать его в расширении Sphinx/docutils... и затем создать тему Sphinx, которая знала об этой функциональности.

Это будет немного больше работы, но даст вам больше гибкости.

Ответ 2

Вам не нужна пользовательская тема. Используйте встроенный container директив, который позволяет добавлять пользовательские css-классы в блоки и переопределять существующую тему, чтобы добавить некоторый javascript для добавления функции show/hide.

Это _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_stylesheet('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

Ответ 3

Тема облачного сфинкса имеет пользовательскую директиву html-toggle которая предоставляет переключаемые разделы. Цитировать с их веб-страницы:

Вы можете пометить разделы с помощью .. rst-class:: html-toggle, что сделает раздел по умолчанию разделенным на html по умолчанию, с помощью ссылки переключения "show section" справа от заголовка.

Вот ссылка на их тестовую демонстрационную страницу.

Ответ 4

Существует очень упрощенное расширение, обеспечивающее именно эту функцию: https://github.com/scopatz/hiddencode

Это работает довольно хорошо для меня.