如何在reStructuredText中为Read the Docs的CSV表格设置高度？

我之前也碰到过一模一样的问题！Sphinx（Read the Docs底层用的文档生成工具）的csv-table指令本身确实不支持:height:属性，因为它默认会把所有行都渲染成普通的HTML表格，没有内置的滚动容器。不过有两个非常实用的解决办法，亲测有效：

方法一：用自定义CSS全局设置滚动表格 #

这个方法适合你有多个大表格需要统一样式的场景：

• 在你的Sphinx项目的_static文件夹里新建一个custom.css文件，写入以下样式：

/* 自定义滚动表格容器 */
.scroll-table-container {
  max-height: 400px; /* 这里设置你想要的固定高度 */
  overflow-y: auto;
  margin: 1em 0;
}
/* 确保表格宽度适配容器 */
.scroll-table-container table {
  width: 100%;
  border-collapse: collapse;
}

• 在项目根目录的conf.py文件中添加一行，引入这个自定义CSS：

html_css_files = ['custom.css']

• 在你的rst文档里，用容器包裹CSV表格：

.. container:: scroll-table-container

   .. csv-table:: 你的大表格标题
      :header-rows: 1
      :file: path/to/your/large.csv

方法二：用Raw HTML临时包裹单个表格 #

如果只是个别表格需要设置高度，不想改全局CSS，可以直接用原生HTML包裹：

• 在rst文档里，先用Raw HTML标签创建一个带滚动属性的容器：

.. raw:: html

   <div style="max-height: 300px; overflow-y: auto; margin: 1em 0;">

• 插入你的CSV表格代码：

.. csv-table:: 单个需要滚动的表格
   :header-rows: 1
   :file: path/to/your/large.csv

• 最后闭合Raw HTML容器：

.. raw:: html

   </div>

这种方式灵活度高，不需要额外配置，直接在需要的地方插入即可。

核心原理就是给表格套一个有固定高度和垂直滚动属性的容器，让浏览器自动处理超出部分的滚动，而不是让表格本身无限延伸。

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