gh-105812: [PoC] add :deco: role and adapt some rst files

[erlend-aasland]

• Issue: Docs: make it easier to reference and markup decorators #105812

---

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

[erlend-aasland]

This works fine for :deco:`mydeco` , but fails for :deco:`!mydeco` . I know nothing about Sphinx internals; pointers appreciated :)

[erlend-aasland]

I'm probably misusing the docutils/Sphinx API here, but I got this working using a custom inner node class. Perhaps overriding result_nodes() is more preferable?

Anyway, here are some screenshots:

[erlend-aasland]

Well, older versions of Sphinx don't like it; I guess I should consider overriding result_nodes() instead.

[erlend-aasland]

I'll work on this locally instead of polluting the CPython PR list.

[AA-Turner]

@erlend-aasland I'd accept this as a feature in Sphinx, if you'd be interested -- we could then backport here.

A

[erlend-aasland]

@erlend-aasland I'd accept this as a feature in Sphinx, if you'd be interested -- we could then backport here.

Definitely! I need some help hashing this out; I haven't found the time to delve into the nitty gritty Sphinx details.

[erlend-aasland]

@AA-Turner: I created sphinx-doc/sphinx#13105.