Sphinx HTML输出格式问题：如何换行过长的函数名？

方案1：自定义CSS强制换行（通用所有主题） #

直接通过自定义CSS覆盖主题样式，适配所有主题：

1. 在Sphinx项目的_static目录下创建custom.css文件（无此目录则新建）
2. 写入以下CSS代码：

/* 处理主页面函数签名蓝色框内的长名称换行 */
.sig-object {
    white-space: pre-wrap;
    word-break: break-all;
}

/* 针对RTD主题优化侧边栏长名称换行 */
.wy-menu-vertical a {
    white-space: normal;
    word-wrap: break-word;
}

3. 在项目根目录的conf.py中启用自定义CSS：

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

执行make html重新构建文档后，主页面的长函数/模块名即可自动换行。

方案2：调整sphinx-apidoc生成逻辑简化名称 #

如果不想修改样式，可以通过调整apidoc参数缩短显示的名称：

• 生成rst文件时添加--module-first参数，让模块名仅显示最后一部分：

sphinx-apidoc --module-first -o docs/source 你的包路径

• 或者在自动生成的rst文件中，给automodule指令添加:short-name:选项（需Sphinx版本支持）：

.. automodule:: monai_inference_from_nnunet_folder.custom_transforms.custom_transforms_array
   :members:
   :undoc-members:
   :show-inheritance:
   :short-name:

方案3：RTD主题专属优化 #

若坚持使用sphinx-rtd-theme，可在conf.py中添加主题配置增强适配：

html_theme_options = {
    'navigation_depth': 4,
    'wrap_pages': True
}

wrap_pages参数会让页面内容自动适配宽度，配合自定义CSS能更好解决换行问题。

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