如何让带短横线的函数名在Sphinx侧边栏正常显示？

核心原因 #

Sphinx的function指令原本是为Python函数设计的，而Python函数名不允许用短横线，所以内部处理索引时，会把短横线识别成无效分隔符，导致带短横线的函数无法被Furo主题的侧边栏索引抓取到。

修复&排查方案 #

1. 用:name:手动指定索引名（最快捷） #

给function指令加:name:参数，把短横线换成下划线作为内部索引标识，不影响函数名的显示：

.. function:: count-non-empty(nodeset)
   :name: count_non_empty

   Returns the number of non-empty members of ``nodeset``.

这样Sphinx会用count_non_empty作为索引名，避开短横线的限制，Furo就能正常在侧边栏显示这个函数条目。

2. 自定义指令批量处理（适合大量函数） #

如果有很多带短横线的函数，可在项目conf.py里写个小扩展自动处理：

from sphinx.directives import ObjectDescription

class CustomFunctionDirective(ObjectDescription):
    def handle_signature(self, sig, signode):
        # 自动把函数名里的短横线换成下划线作为索引名
        func_name = sig.split('(')[0]
        self.env.ref_context['py:func'] = func_name.replace('-', '_')
        return super().handle_signature(sig, signode)

def setup(app):
    app.add_directive('custom-function', CustomFunctionDirective)

之后在rst文件里用自定义指令代替function：

.. custom-function:: count-non-empty(nodeset)

   Returns the number of non-empty members of ``nodeset``.

3. 检查版本兼容性 #

试试升级Furo到最新版本，或者降级到和Sphinx 7.2.5稳定兼容的版本——部分旧版Furo可能对特殊字符的索引处理有bug。

4. 查看构建日志找线索 #

执行构建命令时加-v参数看详细日志：

sphinx-build -v source build/html

如果日志里有关于索引生成的警告，比如提示“无法处理含短横线的名称”，就可以确认是Sphinx核心的索引限制，直接用方法1解决就行。

内容的提问来源于stack exchange，提问作者Hélène Martin