如何在 Sphinx 文档中将成员注释为抽象？

Question

以下两个属性定义在 Sphinx 中显示完全相同

autodoc

HTML 输出：

@property
def concrete(self):
    """This is the concrete docstring"""
    pass

@abstractproperty
def abstract(self):
    """This is the abstract docstring"""
    pass

Sphinx 有办法用某种标识符来注释抽象方法吗？我希望在我的文档中清楚地表明我的 ABC 的哪些成员需要实施，以及一旦定义了所需的成员，您将获得哪些混合免费赠品。

Answer 1

Sphinx 好像做不到。自 2011 年以来，它在 Sphinx 的 bitbucket 中被标记为未解决问题，并被标记为 Sphinx 未来版本的里程碑。

Answer 2

@abc.abstractmethod

现在出现在 Sphinx 输出上

build.sh

sphinx-build . out

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = [ 'sphinx.ext.autodoc' ]
autodoc_default_options = {
    'members': True,
    # Does now show base classes otherwise... why such bad defaults?
    # But with this it does show useless bases like `object`. What is one to do?
    'show-inheritance': True,
}

index.rst

.. automodule:: main

main.py

#!/usr/bin/env python

import abc

class CanFly(metaclass=abc.ABCMeta):
    '''
    doc
    '''

    @abc.abstractmethod
    def fly(self) -> str:
        '''
        doc
        '''
        pass

class Bird(CanFly):
    '''
    doc
    '''

    def fly(self):
        '''
        doc
        '''
        return 'Bird.fly'

class Bat(CanFly):
    '''
    doc
    '''

    def fly(self):
        '''
        doc
        '''
        return 'Bat.fly'

def send_mail(flyer: CanFly) -> str:
    '''
    doc
    '''
    return flyer.fly()

assert send_mail(Bird()) == 'Bird.fly'
assert send_mail(Bat()) == 'Bat.fly'

requirements.txt

Sphinx==6.1.3

有了这个，输出在方法名称前显示

abstract

：

但是 TODO：派生类方法中没有明确表示它实现了抽象方法，类型信息也没有被携带。

:abstractmethod:

记录在：https://sphinx-doc.org/en/master/usage/restructuredtext/… | github.com/sphinx-doc/sphinx/pull/6365

TODO 如何使用它。一定要从

.rst

使用吗？或者有没有文档字符串的方法？