docs/sphinx/compat.py

2 Sphinx cross-version compatibility goop
18 import sphinx
19 from sphinx import addnodes, util
20 from sphinx.directives import ObjectDescription
21 from sphinx.environment import BuildEnvironment
22 from sphinx.roles import XRefRole
23 from sphinx.util import docfields
24 from sphinx.util.docutils import (
29 from sphinx.util.typing import TextlikeNode
32 MAKE_XREF_WORKAROUND = sphinx.version_info[:3] < (4, 1, 0)
38 if sphinx.version_info[:3] >= (4, 0, 0):
50     This helper preserves error parsing context across sphinx versions.
57         # Modern sphinx (6.2.0+) supports proper offsetting for
74 # xref compatibility hacks for Sphinx < 4.1 #
77 # When we require >= Sphinx 4.1, the following function and the
84     self: sphinx.util.docfields.Field,
95     Compatibility workaround for Sphinx versions prior to 4.1.0.
97     Older sphinx versions do not use the domain's XRefRole for parsing
102     This workaround isn't brick-for-brick compatible with modern Sphinx
106     It's no worse than what pre-Sphinx 4.1.0 does, so... oh well!
113     # Note: Sphinx's own code ignores the type warning here, too.
124     # these were not supported in Sphinx 3.x either, so nothing of
131     # Code below based mostly on sphinx.roles.XRefRole; run() and
148     # self.inliner.document. Prior to Sphinx 4.1, we don't *have* an
153     # old versions of Sphinx, so at least it won't change in the
181 # Nested parsing error location fix for Sphinx 5.3.0 < x < 6.2.0 #
184 # When we require Sphinx 4.x, the TYPE_CHECKING hack where we avoid
188 # When we require Sphinx > 6.2.0, the rest of this compatibility hack
192 SOURCE_LOCATION_FIX = (5, 3, 0) <= sphinx.version_info[:3] < (6, 2, 0)
210         # Work around a sphinx bug and parse the content ourselves.
220             # Sphinx will try to parse the content block itself,
226         # Sphinx workaround: Inject our parsed content and restore state.