Documentation/sphinx/automarkup.py | 78 ++++++++++---------------------------- 1 file changed, 20 insertions(+), 58 deletions(-)
Several of the markup functions contain the same code, calling into
sphinx's pending_xref and resolve_xref functions to add and resolve a
cross-reference, with only a few of the parameters changed (domain,
reference type, markup content). Move this logic to its own function and
reuse it in the markup functions.
No functional change.
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
Documentation/sphinx/automarkup.py | 78 ++++++++++----------------------------
1 file changed, 20 insertions(+), 58 deletions(-)
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index ecf54d22e9dc6ab459a91fde580c1cf161f054ed..8b129835e521428c0bafdc1584c8ce69252a668d 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -128,13 +128,11 @@ def note_failure(target):
# own C role, but both match the same regex, so we try both.
#
def markup_func_ref_sphinx3(docname, app, match):
- cdom = app.env.domains['c']
#
# Go through the dance of getting an xref out of the C domain
#
base_target = match.group(2)
target_text = nodes.Text(match.group(0))
- xref = None
possible_targets = [base_target]
# Check if this document has a namespace, and if so, try
# cross-referencing inside it first.
@@ -146,22 +144,8 @@ def markup_func_ref_sphinx3(docname, app, match):
if (target not in Skipfuncs) and not failure_seen(target):
lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
lit_text += target_text
- pxref = addnodes.pending_xref('', refdomain = 'c',
- reftype = 'function',
- reftarget = target,
- modname = None,
- classname = None)
- #
- # XXX The Latex builder will throw NoUri exceptions here,
- # work around that by ignoring them.
- #
- try:
- xref = cdom.resolve_xref(app.env, docname, app.builder,
- 'function', target, pxref,
- lit_text)
- except NoUri:
- xref = None
-
+ xref = add_and_resolve_xref(app, docname, 'c', 'function',
+ target, contnode=lit_text)
if xref:
return xref
note_failure(target)
@@ -188,13 +172,11 @@ def markup_c_ref(docname, app, match):
RE_typedef: 'type',
}
- cdom = app.env.domains['c']
#
# Go through the dance of getting an xref out of the C domain
#
base_target = match.group(2)
target_text = nodes.Text(match.group(0))
- xref = None
possible_targets = [base_target]
# Check if this document has a namespace, and if so, try
# cross-referencing inside it first.
@@ -206,21 +188,9 @@ def markup_c_ref(docname, app, match):
if not (match.re == RE_function and target in Skipfuncs):
lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
lit_text += target_text
- pxref = addnodes.pending_xref('', refdomain = 'c',
- reftype = reftype_str[match.re],
- reftarget = target, modname = None,
- classname = None)
- #
- # XXX The Latex builder will throw NoUri exceptions here,
- # work around that by ignoring them.
- #
- try:
- xref = cdom.resolve_xref(app.env, docname, app.builder,
- reftype_str[match.re], target, pxref,
- lit_text)
- except NoUri:
- xref = None
-
+ xref = add_and_resolve_xref(app, docname, 'c',
+ reftype_str[match.re], target,
+ contnode=lit_text)
if xref:
return xref
@@ -231,7 +201,6 @@ def markup_c_ref(docname, app, match):
# cross reference to that page
#
def markup_doc_ref(docname, app, match):
- stddom = app.env.domains['std']
#
# Go through the dance of getting an xref out of the std domain
#
@@ -239,22 +208,8 @@ def markup_doc_ref(docname, app, match):
target = match.group(2)
if absolute:
target = "/" + target
- xref = None
- pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
- reftarget = target, modname = None,
- classname = None, refexplicit = False)
- #
- # XXX The Latex builder will throw NoUri exceptions here,
- # work around that by ignoring them.
- #
- try:
- xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc',
- target, pxref, None)
- except NoUri:
- xref = None
- #
- # Return the xref if we got it; otherwise just return the plain text.
- #
+
+ xref = add_and_resolve_xref(app, docname, 'std', 'doc', target)
if xref:
return xref
else:
@@ -265,7 +220,6 @@ def markup_doc_ref(docname, app, match):
# with a cross reference to that page
#
def markup_abi_ref(docname, app, match, warning=False):
- stddom = app.env.domains['std']
#
# Go through the dance of getting an xref out of the std domain
#
@@ -280,7 +234,15 @@ def markup_abi_ref(docname, app, match, warning=False):
kernel_abi.log.warning("%s not found", fname)
return nodes.Text(match.group(0))
- pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref',
+ xref = add_and_resolve_xref(app, docname, 'std', 'ref', target)
+ if xref:
+ return xref
+ else:
+ return nodes.Text(match.group(0))
+
+def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
+ dom_obj = app.env.domains[domain]
+ pxref = addnodes.pending_xref('', refdomain = domain, reftype = reftype,
reftarget = target, modname = None,
classname = None, refexplicit = False)
@@ -289,8 +251,8 @@ def markup_abi_ref(docname, app, match, warning=False):
# work around that by ignoring them.
#
try:
- xref = stddom.resolve_xref(app.env, docname, app.builder, 'ref',
- target, pxref, None)
+ xref = dom_obj.resolve_xref(app.env, docname, app.builder, reftype,
+ target, pxref, contnode)
except NoUri:
xref = None
#
@@ -298,8 +260,8 @@ def markup_abi_ref(docname, app, match, warning=False):
#
if xref:
return xref
- else:
- return nodes.Text(match.group(0))
+
+ return None
#
# Variant of markup_abi_ref() that warns whan a reference is not found
---
base-commit: a4cda136f021ad44b8b52286aafd613030a6db5f
change-id: 20250407-automarkup-resolve-xref-helper-d9dcec094f28
Best regards,
--
Nícolas F. R. A. Prado <nfraprado@collabora.com>
On Mon, Apr 07, 2025 at 11:42:03AM -0400, Nícolas F. R. A. Prado wrote: > Several of the markup functions contain the same code, calling into > sphinx's pending_xref and resolve_xref functions to add and resolve a > cross-reference, with only a few of the parameters changed (domain, > reference type, markup content). Move this logic to its own function and > reuse it in the markup functions. > > No functional change. > > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com> > --- > Documentation/sphinx/automarkup.py | 78 ++++++++++---------------------------- > 1 file changed, 20 insertions(+), 58 deletions(-) > > diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py > index ecf54d22e9dc6ab459a91fde580c1cf161f054ed..8b129835e521428c0bafdc1584c8ce69252a668d 100644 > --- a/Documentation/sphinx/automarkup.py > +++ b/Documentation/sphinx/automarkup.py > @@ -128,13 +128,11 @@ def note_failure(target): > # own C role, but both match the same regex, so we try both. > # > def markup_func_ref_sphinx3(docname, app, match): > - cdom = app.env.domains['c'] > # > # Go through the dance of getting an xref out of the C domain > # I just noticed I missed these comments, they refer to the code that was moved to the helper. I'll delete them in the markup functions for v2. Thanks, Nícolas
© 2016 - 2026 Red Hat, Inc.