Sphinx RTD主题网格表格不自动换行超出屏幕宽度问题求助

网格表格无法自动换行的核心原因是单元格内的长类名、配置属性名属于行内代码元素，默认CSS规则不允许断字，从而撑宽列宽导致整体表格超出屏幕。可用解决方案如下：

方案1：修改表格语法（无需改配置，兼容性最好） #

弃用原始网格表格，改用reStructuredText的列表表格语法，可手动指定列宽比例，适配性更强：

.. list-table:: 凭据工厂配置说明
   :widths: 45 55
   :header-rows: 1

   * - 凭据工厂及额外配置属性
     - 说明
   * - | ``nl.nn.credentialprovider.PropertyFileCredentialFactory``
       | 附带配置项：``credentialFactory.map.properties``
     - | 从属性文件读取凭据
       | ``credentialFactory.map.properties`` 存储用户名密码的文件名称，文件内容格式参考前文示例
   * - | ``nl.nn.credentialprovider.FileSystemCredentialFactory``
       | 附带配置项：
       | ``credentialFactory.filesystem.usernamefile``
       | ``credentialFactory.filesystem.passwordfile``
       | ``credentialFactory.filesystem.root``
       | 默认值分别为 ``username``、``password``、``/etc/secrets``
     - | 用户名和密码存储在独立的文本文件中
       | 上述用户名、密码文件的配置路径，均相对于 ``credentialFactory.filesystem.root`` 配置的根路径
   * - | ``nl.nn.credentialprovider.AnsibleVaultCredentialFactory``
       | 附带配置项：``credentialFactory.ansibleVault.vaultFile``、``credentialFactory.keyFile``
     - 从Ansible vault读取凭据，额外配置项分别对应vault文件路径和密钥文件路径
   * - | ``nl.nn.credentialprovider.WebSphereCredentialFactory``
       | 无额外配置项
     - 读取Websphere Application Server中配置的凭据

其中:widths:参数可根据实际需求调整两列的宽度分配比例。

方案2：添加自定义CSS强制换行 #

如果不想修改原有表格写法，可通过自定义CSS修改行内代码的断行规则：

1. 在Sphinx项目的_static目录下新建custom.css文件，写入以下内容：

/* 强制表格内的行内代码支持断行 */
table code, table tt {
    white-space: pre-wrap !important;
    word-wrap: break-word !important;
    word-break: break-all !important;
}
/* 可选：限制第一列最大宽度，避免被长代码撑宽 */
.wy-table-responsive table td:first-child {
    max-width: 45% !important;
}

2. 在项目的conf.py配置文件中添加CSS引用：

html_static_path = ['_static']
html_css_files = [
    'custom.css',
]

方案3：升级主题版本（可选优化） #

你当前使用的sphinx-rtd-theme 0.5.2版本较旧，升级到1.0.0及以上版本，默认对响应式表格的处理效果更好，配合上述自定义CSS可完全解决宽度溢出问题。

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