Sphinx框架下能否仅覆写HTML构建器的特定访问函数？

针对你的需求，有两种可靠的方式实现仅修改visit_table和starttag方法，同时保留原有翻译器的所有功能，避免兼容性问题：

方法1：猴子补丁直接修改现有翻译器方法 #

这种方式无需创建新的翻译器类，直接在原有翻译器类上替换目标方法，适配所有构建器（包括RTD的自定义构建器）。

在主题的setup.py中添加如下代码：

from sphinx.application import Sphinx

def patch_translator_methods(app: Sphinx):
    # 获取当前构建器对应的翻译器类
    translator_class = app.registry.translators.get(app.builder.name)
    if not translator_class:
        return

    # 保存原有方法的引用
    original_visit_table = translator_class.visit_table
    original_starttag = translator_class.starttag

    # 自定义visit_table方法，添加Bootstrap表格类
    def custom_visit_table(self, node):
        node.attributes.setdefault('classes', []).extend(['table', 'table-striped', 'table-hover'])
        original_visit_table(self, node)

    # 自定义starttag方法，针对特定标签添加Bootstrap属性
    def custom_starttag(self, node, tagname, *args, **kwargs):
        if tagname == 'table':
            # 合并Bootstrap表格类到现有class属性
            existing_classes = kwargs.pop('class', '').split()
            existing_classes.extend(['table-bordered', 'table-sm'])
            kwargs['class'] = ' '.join(set(existing_classes))
        return original_starttag(self, node, tagname, *args, **kwargs)

    # 替换翻译器类的方法
    translator_class.visit_table = custom_visit_table
    translator_class.starttag = custom_starttag

def setup(app: Sphinx):
    # 在构建器初始化完成后执行补丁
    app.connect('builder-inited', patch_translator_methods)
    # 其他主题初始化逻辑...

优势 #

• 自动适配所有构建器，无需单独针对RTD等平台配置
• 最小侵入性，仅修改需要的方法，保留原有翻译器的全部功能

方法2：动态继承现有翻译器类 #

通过动态继承当前环境的默认翻译器类，仅重写需要修改的方法，再将这个子类设置为对应构建器的翻译器。

示例代码：

from sphinx.application import Sphinx

def setup(app: Sphinx):
    # 获取当前默认的HTML翻译器类作为父类
    base_translator = app.registry.translators.get('html')
    if not base_translator:
        return

    # 动态创建仅增强目标方法的翻译器子类
    class BootstrapEnhancedTranslator(base_translator):
        def visit_table(self, node):
            # 添加Bootstrap表格样式类
            node.attributes.setdefault('classes', []).extend(['table', 'table-responsive'])
            super().visit_table(node)

        def starttag(self, node, tagname, *args, **kwargs):
            # 为表格容器添加滚动适配类
            if tagname == 'div' and 'table-wrapper' in kwargs.get('class', ''):
                kwargs['class'] = f"{kwargs['class']} overflow-auto"
            return super().starttag(node, tagname, *args, **kwargs)

    # 为所有可能的构建器设置该翻译器
    for builder_name in ['html', 'readthedocs', 'readthedocsdirhtml']:
        app.set_translator(builder_name, BootstrapEnhancedTranslator, override=True)

优势 #

• 符合面向对象设计，逻辑清晰易维护
• 保留父类翻译器的所有原生功能，包括第三方平台的自定义逻辑

两种方法都能避免完全覆写翻译器带来的兼容性问题，根据你的代码风格偏好选择即可。

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