如何在Sphinx中使用autoclass让类属性排在方法之前？

以下是几个可行的调整方案：

• 确认配置生效范围
  确保autodoc_member_order = 'groupwise'配置在Sphinx主配置文件conf.py的全局范围内，而非仅在单个rst文档或局部指令中设置。全局配置会作用于所有autoclass指令，局部设置可能会覆盖全局，但groupwise更适合全局统一配置。

• 标记成员类型
  groupwise模式的排序逻辑是属性组优先于方法组，但Sphinx默认会把@property装饰的方法归为方法而非属性。需要手动通过注释标记成员类型：

  class DemoClass:
      """示例类"""
      #: 类属性标记
      class_var = "foo"
  
      def __init__(self):
          #: 实例属性标记
          self.instance_var = "bar"
  
      @property
      #: 将@property标记为属性
      def prop_var(self):
          return self.instance_var
  

  通过:ivar:（实例属性）、:cvar:（类属性）或直接用#:注释，让Sphinx将这些成员归为属性组，自然会排在方法前面。

• 排查配置冲突
  检查conf.py中的autodoc_default_options，如果其中设置了member-order选项（比如'member-order': 'bysource'），会覆盖全局的autodoc_member_order配置。需要移除该选项或改为'member-order': 'groupwise'。

• 手动指定成员顺序（兜底方案）
  如果全局配置仍不生效，可以在autoclass指令中直接指定成员顺序和排序规则：

  .. autoclass:: your_module.DemoClass
     :members: class_var, instance_var, prop_var, demo_method
     :member-order: groupwise
  

  明确列出成员并指定member-order参数，强制按照groupwise规则排序。

• 清理缓存重新构建
  Sphinx的缓存可能导致新配置不生效，执行以下命令清理缓存后重新生成文档：

  make clean
  make html
  

内容的提问来源于stack exchange，提问作者V Surya Kumar