如何在Sphinx文档中显示和隐藏代码？

Question

我想要实现和Sphinx，reStructuredText 显示/隐藏代码片段中提到的相同功能。但是那篇帖子里没有分享任何代码。

Answer 1

SQLAlchemy 文档

SQLAlchemy 的文档使用了一种特殊的扩展工具（https://bitbucket.org/zzzeek/zzzeeksphinx/）。

文档的源文件包含了一些带有自定义选项和标记的格式，就像这个例子：

.. sourcecode:: python+sql
 
    {sql}>>> engine.execute("select 1").scalar()
    select 1
    ()
    {stop}1

这些内容会通过一个特别的 Pygments 词法分析器（PythonWithSQLLexer）和 Pygments 格式化器（PopupSQLFormatter）来处理，从而生成一个“弹出”<div>，里面包含代码片段和一个可以显示/隐藏的链接。源代码可以在 sqlformatter.py 找到。

显示/隐藏的功能是通过 jQuery 的一些魔法在 init.js 中实现的。

文档使用了 Mako 模板系统来生成 HTML 页面（Sphinx 默认的模板系统是 Jinja）。这个配置是通过在 mako.py 中对 TemplateBridge 进行子类化来完成的。

在模板文件 layout.mako 中，指定了 CSS 和 JavaScript 文件（包括 init.js）的路径。想了解更多关于 Sphinx 模板的信息，可以查看 http://sphinx-doc.org/templating.html。

Python 文档

Python 文档中的许多代码示例都有一个“按钮”，可以切换显示交互式提示符（>>>, ...）和输出，这种方式类似于 doctest 风格的代码片段。通过隐藏提示符和输出，代码就更容易被复制和粘贴。这里有几个例子： http://docs.python.org/library/datetime.html#module-datetime。

这个功能是通过 copybutton.js 实现的。