私はSphinxとreStructuredTextを使用してソフトウェアパッケージを文書化しています。
私のドキュメントには、長いコードスニペットがいくつかあります。それらを展開する小さな「表示/非表示」ボタンを使用して、デフォルトで非表示にできるようにしたいと思います(例)。
それを行うための標準的な方法はありますか?
私はSphinxとreStructuredTextを使用してソフトウェアパッケージを文書化しています。
私のドキュメントには、長いコードスニペットがいくつかあります。それらを展開する小さな「表示/非表示」ボタンを使用して、デフォルトで非表示にできるようにしたいと思います(例)。
それを行うための標準的な方法はありますか?
カスタムテーマは必要ありません。組み込みのディレクティブcontainer
を使用して、カスタムcssクラスをブロックに追加し、既存のテーマをオーバーライドしてjavascriptを追加し、show/hide-functionalityを追加します。
これは_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
details
コードを2つの生のHTMLディレクティブでラップすることにより、組み込みの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>
これを行う最も簡単な方法は、特定のhtml要素にこの機能を持つように指示するカスタムSphinxテーマを作成することだと思います。ここでは、小さなJQueryが大いに役立ちます。
ただし、reStructuredTextマークアップでこれを指定できるようにする場合は、次のいずれかを行う必要があります。
これはもう少し手間がかかりますが、柔軟性が増します。
その機能を正確に提供する非常に単純な拡張機能があります:https ://github.com/scopatz/hiddencode
それは私にとってはかなりうまくいきます。
上記の方法はどれも私にはうまくいかないようですので、これが私が最終的にそれを解決した方法です:
substitutions.rst
ソースディレクトリに次の内容のファイルを作成します。
.. |toggleStart| raw:: html
<details>
<summary><a> the title of the collapse-block </a></summary>
.. |toggleEnd| raw:: html
</details>
<br/>
使用するすべてのファイルの先頭に次の行を追加します。折りたたみ可能なブロックを追加します
..include:: substitutions.rst
ここで、コードの一部を折りたたみ可能にするには、次を使用します。
|toggleStart|
the text you want to collapse
..code-block:: python
x=1
|toggleEnd|