diff options
Diffstat (limited to 'sphinx/addnodes.py')
| -rw-r--r-- | sphinx/addnodes.py | 76 |
1 files changed, 53 insertions, 23 deletions
diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 5f371e46b..5645ac91b 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -8,16 +8,12 @@ :license: BSD, see LICENSE for details. """ -import warnings -from typing import Any, Dict, List, Sequence +from typing import TYPE_CHECKING, Any, Dict, List, Sequence from docutils import nodes -from docutils.nodes import Element, Node +from docutils.nodes import Element -from sphinx.deprecation import RemovedInSphinx40Warning - -if False: - # For type annotation +if TYPE_CHECKING: from sphinx.application import Sphinx @@ -108,7 +104,7 @@ class toctree(nodes.General, nodes.Element, translatable): self['caption'] = translated_message def extract_original_messages(self) -> List[str]: - messages = [] # type: List[str] + messages: List[str] = [] # toctree entries messages.extend(self.get('rawentries', [])) @@ -213,7 +209,7 @@ class desc_content(nodes.General, nodes.Element): class desc_sig_element(nodes.inline): """Common parent class of nodes for inline text of a signature.""" - classes = [] # type: List[str] + classes: List[str] = [] def __init__(self, rawsource: str = '', text: str = '', *children: Element, **attributes: Any) -> None: @@ -342,6 +338,54 @@ 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. + + 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:: + + <pending_xref refdomain="py" reftarget="io.StringIO ...> + <pending_xref_condition condition="resolved"> + <literal> + StringIO + <pending_xref_condition condition="*"> + <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:: + + # When resolved the cross-reference successfully + <reference> + <literal> + StringIO + + # When resolution is failed + <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. + 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. + + .. versionadded:: 4.0 + """ + + class number_reference(nodes.reference): """Node for number references, similar to pending_xref.""" @@ -362,20 +406,6 @@ class literal_strong(nodes.strong, not_smartquotable): """ -class abbreviation(nodes.abbreviation): - """Node for abbreviations with explanations. - - .. deprecated:: 2.0 - """ - - def __init__(self, rawsource: str = '', text: str = '', - *children: Node, **attributes: Any) -> None: - warnings.warn("abbrevition node for Sphinx was replaced by docutils'.", - RemovedInSphinx40Warning, stacklevel=2) - - super().__init__(rawsource, text, *children, **attributes) - - class manpage(nodes.Inline, nodes.FixedTextElement): """Node for references to manpages.""" |