How to annotate a member as abstract in Sphinx documentation?

Question

The following two property definitions show up exactly the same in Sphinx autodoc HTML output:

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

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

Does Sphinx have a way to annotate the abstract methods with some kind of identifier? I'd like it to be obvious in my documentation which members of my ABC are required to implement, and which are mixin freebies you get once the required ones are defined.

Answer 1

It does not seem as if Sphinx is able to do that. It is marked as an open issue at Sphinx's bitbucket since 2011 and flagged as milestone for a future version of Sphinx.

Answer 2

@abc.abstractmethod now shows up on Sphinx output

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

And with this, the output shows abstract before the method name:

but TODO: there is no clear indication in the derived class method that it implements an abstract method, and typing information is not carried over either.

:abstractmethod:

Documented at: https://sphinx-doc.org/en/master/usage/restructuredtext/… | github.com/sphinx-doc/sphinx/pull/6365

TODO how to use it. Do you have to use it from the .rst? Or is there a way from the docstring?