Python Sphinx文档缩进问题排查（pytket项目）

问题概述 #

维护pytket Python包文档时，发现所有C++枚举的Python绑定模块生成的HTML文档存在两个问题：

• API内容缩进异常，页面显示排版混乱
• 页面中莫名出现不应显示的“Members:”文本

涉事的RST源码如下：

.. currentmodule:: pytket._tket.circuit.OpType
.. autoclass:: pytket._tket.circuit.OpType
    :members:

当前使用的Sphinx及相关依赖版本：

• sphinx==6.1.0
• sphinx_autodoc_annotation==1.0post1
• sphinx-book-theme==1.0.1
• enum-tools[sphinx]==0.1.0

已尝试修改RST语法、更换主题、替换sphinx-autodoc-typehints插件，均未解决问题。

可行解决方案尝试 #

1. 修复依赖版本兼容性 #

enum-tools[sphinx] 0.1.0是较旧版本，可能未适配Sphinx 6.x的API变更。可以尝试两种调整方式：

• 降级Sphinx到5.x稳定版本：

pip install sphinx==5.3.0

• 升级enum-tools到最新版本（当前最新为0.11.0）：

pip install --upgrade enum-tools[sphinx]

2. 自定义Sphinx模板修正渲染逻辑 #

如果版本调整无效，可以通过自定义模板覆盖枚举类的默认渲染行为，移除多余标识并修复缩进：

1. 在文档根目录创建_templates/autosummary/class.rst文件
2. 写入以下模板代码：

{% extends "autosummary/class.rst" %}
{% block members %}
  {% if members %}
    {% for member in members %}
      - :attr:`{{ member }}`
    {% endfor %}
  {% endif %}
{% endblock %}

该模板会替换默认的成员渲染逻辑，避免生成多余的“Members:”标签，并统一缩进格式。

3. 通过conf.py过滤多余内容 #

在项目的conf.py中添加自定义钩子，过滤枚举类生成过程中可能产生的多余节点：

import enum

def skip_enum_members_label(app, what, name, obj, skip, options):
    # 针对枚举类，跳过可能生成"Members:"的自动渲染节点
    if what == 'class' and isinstance(obj, enum.EnumMeta):
        return True
    return skip

def setup(app):
    app.connect('autodoc-skip-member', skip_enum_members_label)

4. 手动指定枚举成员替代自动生成 #

放弃:members:自动枚举所有成员，手动列出需要展示的枚举值，完全控制文档内容格式：

.. currentmodule:: pytket._tket.circuit.OpType
.. autoclass:: pytket._tket.circuit.OpType
    :members: H, X, Y, Z, CX, CY, CZ

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