Merge branch '5.x'

# Conflicts:
#	CHANGES
#	doc/conf.py
#	sphinx/__init__.py
#	sphinx/builders/html/__init__.py
#	sphinx/domains/python.py
#	tests/test_build_html.py

1 files changed, 21 insertions, 22 deletions

diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index e23f570d7..e22ce5fa2 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -1,4 +1,4 @@
-"""Additional docutils nodes."""
+"""Document tree nodes that Sphinx defines on top of those in Docutils."""
 
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
 
@@ -119,7 +119,7 @@ class toctree(nodes.General, nodes.Element, translatable):
 #############################################################
 
 class _desc_classes_injector(nodes.Element, not_smartquotable):
-    """Helper base class for injecting a fixes list of classes.
+    """Helper base class for injecting a fixed list of classes.
 
     Use as the first base class.
     """
@@ -390,7 +390,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
 
 class centered(nodes.Part, nodes.TextElement):
-    """Deprecated."""
+    """This node is deprecated."""
 
 
 class acks(nodes.Element):
@@ -455,13 +455,18 @@ class pending_xref(nodes.Inline, nodes.Element):
 
 
 class pending_xref_condition(nodes.Inline, nodes.TextElement):
-    """Node for cross-references that are used to choose appropriate
-    content of the reference by conditions on the resolving phase.
+    """Node representing a potential way to create a cross-reference and the
+    condition in which this way should be used.
 
-    When the :py:class:`pending_xref` node contains one or more
-    **pending_xref_condition** nodes, the cross-reference resolver
-    should choose the content of the reference using defined conditions
-    in ``condition`` attribute of each pending_xref_condition nodes::
+    This node is only allowed to be placed under a :py:class:`pending_xref`
+    node.  A **pending_xref** node must contain either no **pending_xref_condition**
+    nodes or it must only contains **pending_xref_condition** nodes.
+
+    The cross-reference resolver will replace a :py:class:`pending_xref` which
+    contains **pending_xref_condition** nodes by the content of exactly one of
+    those **pending_xref_condition** nodes' content. It uses the **condition**
+    attribute to decide which **pending_xref_condition** node's content to
+    use. For example, let us consider how the cross-reference resolver acts on::
 
         <pending_xref refdomain="py" reftarget="io.StringIO ...>
             <pending_xref_condition condition="resolved">
@@ -471,32 +476,26 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement):
                 <literal>
                     io.StringIO
 
-    After the processing of cross-reference resolver, one of the content node
-    under pending_xref_condition node is chosen by its condition and to be
-    removed all of pending_xref_condition nodes::
+    If the cross-reference resolver successfully resolves the cross-reference,
+    then it rewrites the **pending_xref** as::
 
-        # When resolved the cross-reference successfully
         <reference>
             <literal>
                 StringIO
 
-        # When resolution is failed
+    Otherwise, if the cross-reference resolution failed, it rewrites the
+    **pending_xref** as::
+
         <reference>
             <literal>
                 io.StringIO
 
-    .. note:: This node is only allowed to be placed under pending_xref node.
-              It is not allows to place it under other nodes.  In addition,
-              pending_xref node must contain only pending_xref_condition
-              nodes if it contains one or more pending_xref_condition nodes.
-
-    The pending_xref_condition node should have **condition** attribute.
+    The **pending_xref_condition** node should have **condition** attribute.
     Domains can be store their individual conditions into the attribute to
     filter contents on resolving phase.  As a reserved condition name,
     ``condition="*"`` is used for the fallback of resolution failure.
     Additionally, as a recommended condition name, ``condition="resolved"``
-    is used for the representation of resolstion success in the intersphinx
-    module.
+    represents a resolution success in the intersphinx module.
 
     .. versionadded:: 4.0
     """