Add class directives for xml.dom

[AA-Turner]

Required for #138418.

A

---

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

[serhiy-storchaka]

I have great doubts about these changes. Because all these classes are not defined in the xml.dom module. This is not description of concrete classes, this is description of ephemeral interfaces. Concrete classes are defined in the minidom submodule and in third-party modules. Adding class directives here will create wrong index entries and add wrong user visible information.

Try to add :no-typesetting: and :no-index-entry: options. Not sure about :no-contents-entry:. Will this be of any benefit?

[AA-Turner]

This is not description of concrete classes, this is description of ephemeral interfaces.

Sphinx doesn't have a .. py:interface:: or .. py:protocol:: directive, so class is the best thing we can do. Would you be happier with an admonition on each directive reminding the reader that they're protocol classes?

I think it would be useful to add them, but I'm happy to revert to just adding the targets if you still have reservations.

A

[serhiy-storchaka]

User should not see class Element here, nor the entry "Element (xml.dom class)", because xml.dom.Element does not exist.

It would be nice to make some class references referring to corresponding section in this file, for example, :class:`Document` in the xml.dom.minidom.parse() description to Document Objects. But not for all (for example NodeList does not exist, it is just a list). Sphinx is bad in using nested markup, so we cannot make a link from Document formatted as class to arbitrary anchor. Can we? If this is possible, it would be an ideal variant -- make all class references inert and add links manually.

Before we find a satisfying solution, it is better to leave unresolved references as a reminder.

[AA-Turner]

Ok, I will close this for now & we can revisit it later, I will make a smaller change to #138418.

A