GH-121970: Replace custom abstract method directive with the :abstract: option

[AA-Turner]

This removes our custom .. abstractmethod:: directive in favour of Sphinx's :abstractmethod: directive option. There is a minor change to rendered output, which I will paste in a comment below.

A

• Issue: Improve and reorganise pyspecific #121970

---

📚 Documentation preview 📚: https://cpython-previews--129311.org.readthedocs.build/

[AA-Turner]

Current (https://docs.python.org/3/library/os.html#os.PathLike.__fspath__):

Proposed (https://cpython-previews--129311.org.readthedocs.build/en/129311/library/os.html#os.PathLike.__fspath__):

A

[AlexWaygood]

Hrm... I weakly prefer the current rendering. The PyAbstractMethod class in pyspecific.py doesn't seem like that much of a maintenance burden here?

[AA-Turner]

I suppose it's more of a design point than a question of maintenance burden. Sphinx's default Python domain should be good enough to document the Python documentation mostly using defaults. We will have some custom logic (e.g. for pydoc, or Misc/NEWS), but when documenting pure-Python objects, I would to get to a point where we don't patch Sphinx.

This is very likely to involve upstream changes though (made easier by the fact we now have decoupled our version support from downstream Linux distros). Is your preference to show e.g. "abstract method __fspath__()"? For methods in general we don't show the method prefix, but we could make an exception here?

A

[AlexWaygood]

Is your preference to show e.g. "abstract method fspath()"? For methods in general we don't show the method prefix, but we could make an exception here?

Referring to it as "abstractmethod" or "abstract method" rather than simply "abstract" does make sense to me, because the decorator is abc.abstractmethod (not abc.abstract). Also, the decorator doesn't have any effect if you apply it to a non-method, so I'm not sure what an abstract non-method function would look like!

[AA-Turner]

I've opened sphinx-doc/sphinx#13271 on the Sphinx side.

The three options we have are (1) keeping abstract, (2) using abstractmethod, or (3) using abstract method. The third has some symmetry with abstract properties, which are currently documented as abstract property.

• abstract property
• abstract method

A