Sphinx autosummary生成表格中的文本自动换行问题

我之前也碰到过一模一样的问题！Autosummary生成的默认表格确实会把长描述文本挤在一行，导致出现讨厌的横向滚动条，下面几个实用的方法应该能帮你彻底解决：

方法一：自定义CSS样式（最推荐，简单高效） #

这是最快见效的方案，只需要给autosummary表格添加几行CSS规则，强制文本自动换行：

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

/* 让autosummary表格自适应容器宽度 */
table.autosummary {
  table-layout: fixed;
  width: 100%;
}

/* 针对表格的最后一列（描述列）设置自动换行 */
table.autosummary td:last-child {
  white-space: pre-wrap;
  word-wrap: break-word;
  padding-right: 1em; /* 可选：增加右侧内边距，让文本不贴边 */
}

2. 在项目的conf.py文件中配置加载这个自定义CSS：

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

重新生成文档后，你会发现描述文本会自动根据表格宽度换行，再也没有横向滚动条了！

方法二：修改Autosummary的模板文件 #

如果CSS方法没有生效（可能是主题样式优先级更高），可以直接修改autosummary的表格模板：

1. 在你的项目根目录创建_templates/autosummary文件夹，把Sphinx安装目录中autosummary/templates/autosummary/table.rst文件复制到这里（如果找不到，可以直接新建一个）。

2. 打开复制后的table.rst，找到描述列对应的<td>标签，添加样式属性：

<td style="white-space: pre-wrap; word-wrap: break-word;">{{ item.summary|e }}</td>

这样直接在模板里给描述列设置换行规则，优先级更高，肯定能生效。

方法三：优化Docstring的换行方式（辅助方案） #

你之前尝试的<br />或|没用，是因为Sphinx解析docstring时会过滤掉这些标记。如果想在docstring里手动控制换行，可以用reStructuredText的换行语法：在需要换行的地方加两个空格再回车，或者用.. line-block::指令包裹文本：

def my_function():
    """这是一个很长的描述文本，  
    这里加两个空格再回车，
    生成文档时会自动换行。

    或者用line-block指令：
    .. line-block::
       这是第一行描述
       这是第二行描述
       这是第三行描述
    """
    pass

不过这个方法只能辅助手动控制换行，还是CSS方法更能解决全局的自动换行问题。

内容的提问来源于stack exchange，提问作者Louis-Justin Tallot