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

[miss-islington-app]

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @AA-Turner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 30e892473e0dfe5c3fecabcaac420cefe45e2ed4 3.13

[miss-islington-app]

Sorry, @AA-Turner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 30e892473e0dfe5c3fecabcaac420cefe45e2ed4 3.12

[bedevere-app]

GH-130440 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-130439 is a backport of this pull request to the 3.13 branch.