如何在reStructuredText中嵌入带折叠下拉的大型JSON对象

方法1：使用Sphinx扩展 sphinx-jsonschema #

这个扩展专门用来渲染JSON Schema，自动生成带折叠功能的HTML结构，完美适配需求。

步骤： #

1. 安装扩展
   用pip执行安装命令：

   pip install sphinx-jsonschema
   

2. 在Sphinx配置中启用扩展
   编辑项目的conf.py文件，将sphinx_jsonschema加入扩展列表：

   extensions = [
       # 保留原有扩展
       'sphinx_jsonschema',
   ]
   

3. 在reStructuredText中嵌入JSON
   支持直接写入JSON内容或引用外部JSON文件：
   • 直接嵌入内容：

     .. jsonschema::
         {
             "$id": "https://example.com/person.schema.json",
             "$schema": "http://json-schema.org/draft-07/schema#",
             "title": "Person",
             "type": "object",
             "properties": {
               "subType1": {
                 "type": "object",
                 "description": "A sub type with additionalProperties false.",
                 "properties": {
                   "subProp1": {
                     "type": "number"
                   }
                 },
                 "additionalProperties": false
               },
               "subType2": {
                 "type": "object",
                 "description": "A sub type with additionalProperties true.",
                 "properties": {
                   "subProp2": {
                     "type": "number"
                   }
                 },
                 "additionalProperties": true
               },
               "anInt": {
                 "type": "integer",
                 "description": "This is an integer, it should not show additional properties. (issue #132)"
               }
             },
             "additionalProperties": {
               "type": "object",
               "description": "additionalProperties schema.",
               "properties": {
                 "propA": {
                   "type": "number"
                 }
               }
             }
         }
     

   • 引用外部文件（例如person.schema.json）：

     .. jsonschema:: person.schema.json
     

4. 生成HTML
   运行sphinx-build生成HTML后，所有JSON对象节点（如properties、subType1、subType2）都会自动带有折叠/展开按钮，点击即可切换显示状态，方便用户导航。

方法2：自定义HTML+CSS+JS实现折叠 #

如果不想依赖第三方扩展，可以直接在reStructuredText中嵌入自定义代码，手动实现折叠功能：

步骤： #

在reST文档中插入以下代码：

.. raw:: html

    <style>
        .json-collapse {
            margin-left: 20px;
            display: none;
        }
        .json-toggle {
            cursor: pointer;
            font-weight: bold;
        }
        .json-toggle::before {
            content: "▶ ";
            font-size: 0.8em;
        }
        .json-toggle.open::before {
            content: "▼ ";
        }
        pre.json-code {
            background: #f5f5f5;
            padding: 10px;
            border-radius: 4px;
            font-family: monospace;
            white-space: pre-wrap;
        }
    </style>

    <div class="json-container">
        <pre class="json-code">
{
    "$id": "https://example.com/person.schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Person",
    "type": "object",
    "properties": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
        <div class="json-collapse">
            "subType1": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
                <div class="json-collapse">
                    "type": "object",
                    "description": "A sub type with additionalProperties false.",
                    "properties": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
                        <div class="json-collapse">
                            "subProp1": {
                                "type": "number"
                            }
                        }</div>,
                    "additionalProperties": false
                }</div>,
            "subType2": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
                <div class="json-collapse">
                    "type": "object",
                    "description": "A sub type with additionalProperties true.",
                    "properties": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
                        <div class="json-collapse">
                            "subProp2": {
                                "type": "number"
                            }
                        }</div>,
                    "additionalProperties": true
                }</div>,
            "anInt": {
                "type": "integer",
                "description": "This is an integer, it should not show additional properties. (issue #132)"
            }
        }</div>,
    "additionalProperties": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
        <div class="json-collapse">
            "type": "object",
            "description": "additionalProperties schema.",
            "properties": <span class="json-toggle" onclick="toggleCollapse(this)">{</span>
                <div class="json-collapse">
                    "propA": {
                        "type": "number"
                    }
                }</div>
        }</div>
}</pre>
    </div>

    <script>
        function toggleCollapse(element) {
            element.classList.toggle('open');
            const nextDiv = element.nextElementSibling;
            nextDiv.style.display = nextDiv.style.display === 'block' ? 'none' : 'block';
        }
    </script>

效果说明 #

这段代码会给每个对象节点的左大括号添加可点击的折叠按钮，点击后展开/收起对应子内容。CSS负责样式美化，JS处理折叠逻辑，生成的HTML完全满足需求，无需额外依赖。

注意：该方法需要手动拆分JSON层级，适合结构固定、改动较少的场景；如果JSON频繁更新，推荐使用方法1的扩展自动处理。

内容的提问来源于stack exchange，提问作者BhanuKiran