From ea6a659e991ac1c850218f6d6aa684cd86995e4d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 3 Sep 2025 01:18:35 +0100 Subject: [PATCH 1/3] Add class directives for ``xml.dom`` --- Doc/library/xml.dom.rst | 90 +++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index f33b19bc2724d0..cb16849aad5263 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -236,7 +236,9 @@ DOM Level 2 added the ability to create new :class:`Document` and Node Objects ^^^^^^^^^^^^ -All of the components of an XML document are subclasses of :class:`Node`. +.. class:: Node + + All of the components of an XML document are subclasses of :class:`Node`. .. attribute:: Node.nodeType @@ -403,14 +405,16 @@ All of the components of an XML document are subclasses of :class:`Node`. NodeList Objects ^^^^^^^^^^^^^^^^ -A :class:`NodeList` represents a sequence of nodes. These objects are used in -two ways in the DOM Core recommendation: an :class:`Element` object provides -one as its list of child nodes, and the :meth:`getElementsByTagName` and -:meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this -interface to represent query results. +.. class:: NodeList + + A :class:`NodeList` represents a sequence of nodes. These objects are used in + two ways in the DOM Core recommendation: an :class:`Element` object provides + one as its list of child nodes, and the :meth:`getElementsByTagName` and + :meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this + interface to represent query results. -The DOM Level 2 recommendation defines one method and one attribute for these -objects: + The DOM Level 2 recommendation defines one method and one attribute for these + objects: .. method:: NodeList.item(i) @@ -442,16 +446,18 @@ If a DOM implementation supports modification of the document, the DocumentType Objects ^^^^^^^^^^^^^^^^^^^^ -Information about the notations and entities declared by a document (including -the external subset if the parser uses it and can provide the information) is -available from a :class:`DocumentType` object. The :class:`DocumentType` for a -document is available from the :class:`Document` object's :attr:`doctype` -attribute; if there is no ``DOCTYPE`` declaration for the document, the -document's :attr:`doctype` attribute will be set to ``None`` instead of an -instance of this interface. +.. class:: DocumentType + + Information about the notations and entities declared by a document (including + the external subset if the parser uses it and can provide the information) is + available from a :class:`DocumentType` object. The :class:`DocumentType` for a + document is available from the :class:`Document` object's :attr:`doctype` + attribute; if there is no ``DOCTYPE`` declaration for the document, the + document's :attr:`doctype` attribute will be set to ``None`` instead of an + instance of this interface. -:class:`DocumentType` is a specialization of :class:`Node`, and adds the -following attributes: + :class:`DocumentType` is a specialization of :class:`Node`, and adds the + following attributes: .. attribute:: DocumentType.publicId @@ -502,9 +508,11 @@ following attributes: Document Objects ^^^^^^^^^^^^^^^^ -A :class:`Document` represents an entire XML document, including its constituent -elements, attributes, processing instructions, comments etc. Remember that it -inherits properties from :class:`Node`. +.. class:: Document + + A :class:`Document` represents an entire XML document, including its constituent + elements, attributes, processing instructions, comments etc. Remember that it + inherits properties from :class:`Node`. .. attribute:: Document.documentElement @@ -582,8 +590,10 @@ inherits properties from :class:`Node`. Element Objects ^^^^^^^^^^^^^^^ -:class:`Element` is a subclass of :class:`Node`, so inherits all the attributes -of that class. +.. class:: Element + + :class:`Element` is a subclass of :class:`Node`, so inherits all the attributes + of that class. .. attribute:: Element.tagName @@ -686,7 +696,9 @@ of that class. Attr Objects ^^^^^^^^^^^^ -:class:`Attr` inherits from :class:`Node`, so inherits all its attributes. +.. class:: Attr + + :class:`Attr` inherits from :class:`Node`, so inherits all its attributes. .. attribute:: Attr.name @@ -719,7 +731,9 @@ Attr Objects NamedNodeMap Objects ^^^^^^^^^^^^^^^^^^^^ -:class:`NamedNodeMap` does *not* inherit from :class:`Node`. +.. class:: NamedNodeMap + + :class:`NamedNodeMap` does *not* inherit from :class:`Node`. .. attribute:: NamedNodeMap.length @@ -743,8 +757,10 @@ of methods on the :class:`Element` objects. Comment Objects ^^^^^^^^^^^^^^^ -:class:`Comment` represents a comment in the XML document. It is a subclass of -:class:`Node`, but cannot have child nodes. +.. class:: Comment + + :class:`Comment` represents a comment in the XML document. It is a subclass of + :class:`Node`, but cannot have child nodes. .. attribute:: Comment.data @@ -759,14 +775,16 @@ Comment Objects Text and CDATASection Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :class:`Text` interface represents text in the XML document. If the parser -and DOM implementation support the DOM's XML extension, portions of the text -enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. -These two interfaces are identical, but provide different values for the -:attr:`nodeType` attribute. +.. class:: Text -These interfaces extend the :class:`Node` interface. They cannot have child -nodes. + The :class:`Text` interface represents text in the XML document. If the parser + and DOM implementation support the DOM's XML extension, portions of the text + enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. + These two interfaces are identical, but provide different values for the + :attr:`nodeType` attribute. + + These interfaces extend the :class:`Node` interface. They cannot have child + nodes. .. attribute:: Text.data @@ -787,8 +805,10 @@ nodes. ProcessingInstruction Objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Represents a processing instruction in the XML document; this inherits from the -:class:`Node` interface and cannot have child nodes. +.. class:: ProcessingInstruction + + Represents a processing instruction in the XML document; this inherits from the + :class:`Node` interface and cannot have child nodes. .. attribute:: ProcessingInstruction.target From 7f8a079e2c17642b63e37d91e6e0c6e7895ce5ef Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:27:27 +0100 Subject: [PATCH 2/3] Suppress self-references --- Doc/library/xml.dom.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index cb16849aad5263..a9adae7a286d96 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -238,7 +238,7 @@ Node Objects .. class:: Node - All of the components of an XML document are subclasses of :class:`Node`. + All of the components of an XML document are subclasses of :class:`!Node`. .. attribute:: Node.nodeType @@ -407,7 +407,7 @@ NodeList Objects .. class:: NodeList - A :class:`NodeList` represents a sequence of nodes. These objects are used in + A :class:`!NodeList` represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an :class:`Element` object provides one as its list of child nodes, and the :meth:`getElementsByTagName` and :meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this @@ -450,13 +450,13 @@ DocumentType Objects Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is - available from a :class:`DocumentType` object. The :class:`DocumentType` for a + available from a :class:`!DocumentType` object. The :class:`!DocumentType` for a document is available from the :class:`Document` object's :attr:`doctype` attribute; if there is no ``DOCTYPE`` declaration for the document, the document's :attr:`doctype` attribute will be set to ``None`` instead of an instance of this interface. - :class:`DocumentType` is a specialization of :class:`Node`, and adds the + :class:`!DocumentType` is a specialization of :class:`Node`, and adds the following attributes: @@ -510,7 +510,7 @@ Document Objects .. class:: Document - A :class:`Document` represents an entire XML document, including its constituent + A :class:`!Document` represents an entire XML document, including its constituent elements, attributes, processing instructions, comments etc. Remember that it inherits properties from :class:`Node`. @@ -592,7 +592,7 @@ Element Objects .. class:: Element - :class:`Element` is a subclass of :class:`Node`, so inherits all the attributes + :class:`!Element` is a subclass of :class:`Node`, so inherits all the attributes of that class. @@ -698,7 +698,7 @@ Attr Objects .. class:: Attr - :class:`Attr` inherits from :class:`Node`, so inherits all its attributes. + :class:`!Attr` inherits from :class:`Node`, so inherits all its attributes. .. attribute:: Attr.name @@ -733,7 +733,7 @@ NamedNodeMap Objects .. class:: NamedNodeMap - :class:`NamedNodeMap` does *not* inherit from :class:`Node`. + :class:`!NamedNodeMap` does *not* inherit from :class:`Node`. .. attribute:: NamedNodeMap.length @@ -759,8 +759,8 @@ Comment Objects .. class:: Comment - :class:`Comment` represents a comment in the XML document. It is a subclass of - :class:`Node`, but cannot have child nodes. + :class:`!Comment` represents a comment in the XML document. + It is a subclass of :class:`Node`, but cannot have child nodes. .. attribute:: Comment.data @@ -777,7 +777,7 @@ Text and CDATASection Objects .. class:: Text - The :class:`Text` interface represents text in the XML document. If the parser + The :class:`!Text` interface represents text in the XML document. If the parser and DOM implementation support the DOM's XML extension, portions of the text enclosed in CDATA marked sections are stored in :class:`CDATASection` objects. These two interfaces are identical, but provide different values for the From 36d6f41edc0bb67069526f18db8d0331ca13d3af Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:29:08 +0100 Subject: [PATCH 3/3] Serhiy's review (getElementsByTagNameNS not defind in Node) --- Doc/library/xml.dom.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst index a9adae7a286d96..f40b408d74fff2 100644 --- a/Doc/library/xml.dom.rst +++ b/Doc/library/xml.dom.rst @@ -410,8 +410,8 @@ NodeList Objects A :class:`!NodeList` represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an :class:`Element` object provides one as its list of child nodes, and the :meth:`getElementsByTagName` and - :meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this - interface to represent query results. + :meth:`getElementsByTagNameNS` methods of :class:`Element` & :class:`Document` + return objects with this interface to represent query results. The DOM Level 2 recommendation defines one method and one attribute for these objects: