minorcleanup

Signed-off-by: Christian López Barrón <[email protected]>

docs/source/conf.py

@@ -22,6 +22,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import functools
 from datetime import datetime
+from sphinxcontrib.doxylink import doxylink as _doxylink_ext
 
 # -- General configuration ------------------------------------------------
 
@@ -262,13 +263,20 @@ def _handle_missing_usd_reference(app, env, node, contnode):
 
 @functools.cache
 def _get_usd_ref_tooltip(app):
+    # TODO: find a less hacky way of achieving this (aiming for consistency with intersphinx titles on hovered links)
     proj, version, __, __ = app.env.intersphinx_named_inventory['usd']['std:doc']['README']
     return f"(in {proj} v{version})"
 
 
+@functools.cache
+def _doxylink_split_explicit_title(text):
+    has_explicit_title, title, part = _doxylink_ext.split_explicit_title(text)
+    part = _doxylink_ext.utils.unescape(part)
+    return has_explicit_title, title, part
+
+
 @functools.cache
 def _get_url_for_target(app, target):
-    from sphinxcontrib.doxylink import doxylink
     pxr_obj_namespace = target.removeprefix('pxr.').replace(".", "")
     pxr_obj_namespace = {
         "UsdInitialLoadSet": "UsdStage::InitialLoadSet",  # there's a level of indirection in the python bindings?
@@ -277,12 +285,11 @@ def _get_url_for_target(app, target):
         "Usd_Term": "primFlags.h",
         "Usd_PrimFlagsConjunction": "primFlags.h",
     }.get(pxr_obj_namespace, pxr_obj_namespace)
-    has_explicit_title, title, part = doxylink.split_explicit_title(pxr_obj_namespace)
-    part = doxylink.utils.unescape(part)
+    __, __, part = _doxylink_split_explicit_title(pxr_obj_namespace)
     url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part]
-    full_url = doxylink.join(_USD_DOXYGEN_ROOT_DIR, url.file)
+    full_url = _doxylink_ext.join(_USD_DOXYGEN_ROOT_DIR, url.file)
     reftitle = _get_usd_ref_tooltip(app)
-    return reftitle, full_url
+    return part + " " + reftitle, full_url
 
 
 def _grill_process_signature(app, what, name, obj, options, signature, return_annotation):
@@ -293,28 +300,30 @@ def _grill_process_signature(app, what, name, obj, options, signature, return_an
     return signature, return_annotation
 
 
-def setup(app):
-    """Setup Sphinx to handle missing USD references. This can be removed when the USD C++ docs ship with an inventory of the USD types for python bindings."""
-    app.connect("autodoc-process-signature", _grill_process_signature)
-    app.connect("missing-reference", _handle_missing_usd_reference)
-    return {"parallel_read_safe": True, "parallel_write_safe": True}
-
-
-from sphinxcontrib.doxylink import doxylink as doxylink_ext
-_doxylink_create_role = doxylink_ext.create_role
+_doxylink_create_role = _doxylink_ext.create_role
 
 
 def _create_doxylink_role_with_title(app, *args, **kwargs):
     doxylink_role = _doxylink_create_role(app, *args, **kwargs)
-    title = _get_usd_ref_tooltip(app)
+    intersphinx_title = _get_usd_ref_tooltip(app)
 
-    def _find_doxygen_link_with_title(*patched_args, **patched_kwargs):
-        inner_result = doxylink_role(*patched_args, **patched_kwargs)
+    def _find_doxygen_link_with_title(name, rawtext, text, *patched_args, **patched_kwargs):
+        inner_result = doxylink_role(name, rawtext, text, *patched_args, **patched_kwargs)
         node = inner_result[0][0]
-        node.attributes['reftitle'] = title
+
+        __, __, part = _doxylink_split_explicit_title(text)
+
+        node.attributes['reftitle'] = part + " " + intersphinx_title
         return inner_result
 
     return _find_doxygen_link_with_title
 
 
-doxylink_ext.create_role = _create_doxylink_role_with_title
+_doxylink_ext.create_role = _create_doxylink_role_with_title
+
+
+def setup(app):
+    """Setup Sphinx to handle missing USD references. This can be removed when the USD C++ docs ship with an inventory of the USD types for python bindings."""
+    app.connect("autodoc-process-signature", _grill_process_signature)
+    app.connect("missing-reference", _handle_missing_usd_reference)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

grill/usd/__init__.py

@@ -49,7 +49,7 @@ def _pruned_prims(prim_range: Usd.PrimRange, predicate):
 
 
 def common_paths(paths: abc.Iterable[Sdf.Path]) -> list[Sdf.Path]:
-    """For the given paths, get those which are the common parents."""
+    """For the given :ref:`paths <glossary:path>`, get those which are the common parents."""
     unique = list()
     for path in sorted(filter(lambda p: p and not p.IsAbsoluteRootPath(), paths)):
         if unique and path.HasPrefix(unique[-1]):  # we're a child, so safe to continue.
@@ -62,10 +62,10 @@ def iprims(stage: Usd.Stage, root_paths: abc.Iterable[Sdf.Path] = tuple(), prune
     """Convenience function that creates an iterator useful for common :ref:`glossary:stage traversal`.
 
     Without keyword arguments, this is the same as calling :usdcpp:`UsdStage::Traverse`, so
-    use that instead when no ``root_paths`` or ``prune_predicate`` are provided.
+    use that instead when neither ``root_paths`` nor ``prune_predicate`` are provided.
 
-    A :usdcpp:`UsdPrimRange` with the provided ``traverse_predicate`` is created for each :usdcpp:`SdfPath` in ``root_paths``,
-    for which :usdcpp:`PruneChildren <UsdPrimRange::iterator::PruneChildren>` is called whenever a traversed :usdcpp:`Prim <UsdPrim>` passes ``prune_predicate``.
+    A :usdcpp:`PrimRage <UsdPrimRange>` with the provided ``traverse_predicate`` is created for each :func:`common <common_paths>` :usdcpp:`Path <SdfPath>` in ``root_paths``,
+    and :usdcpp:`PruneChildren <UsdPrimRange::iterator::PruneChildren>` is called whenever ``prune_predicate`` returns ``True`` for a traversed :usdcpp:`Prim <UsdPrim>`.
 
     """
     if root_paths:  # Traverse only specific parts of the stage.
@@ -82,10 +82,10 @@ def iprims(stage: Usd.Stage, root_paths: abc.Iterable[Sdf.Path] = tuple(), prune
 
 
 @functools.singledispatch
-def edit_context(prim: Usd.Prim, /, query_filter: Usd.PrimCompositionQuery.Filter, arc_predicate: abc.Callable[[Usd.CompositionArc], bool]) -> Usd.EditContext:
-    """:ref:`glossary:composition arcs` target :ref:`LayerStacks <glossary:layerstack>`. These functions provide an :ref:`glossary:edittarget` for the first :usdcpp:`arc <UsdPrimCompositionQueryArc>` in the :ref:`Prims <glossary:prim>`'s :usdcpp:`composition <UsdPrimCompositionQuery>` that returns ``True`` for the given ``arc_predicate``.
+def edit_context(prim: Usd.Prim, /, query_filter: Usd.PrimCompositionQuery.Filter, predicate: abc.Callable[[Usd.CompositionArc], bool]) -> Usd.EditContext:
+    """Get an :ref:`glossary:edittarget` for the first :usdcpp:`arc <UsdPrimCompositionQueryArc>` in the :ref:`Prims <glossary:prim>`'s :usdcpp:`composition <UsdPrimCompositionQuery>` for which the given ``predicate`` returns ``True``.
 
-    Overloaded methods allow for a direct search targetting Payloads, References, Specializes, Inherits and VariantSets.
+    Overloaded implementations allow for a direct search targetting :ref:`glossary:payload`, :ref:`glossary:references`, :ref:`glossary:specializes`, :ref:`glossary:inherits` and :ref:`glossary:variantset`.
 
     This allows for "chained" context switching while preserving the same stage objects.
 
@@ -218,11 +218,11 @@ def Sphere "child" (
     query = Usd.PrimCompositionQuery(prim)
     query.filter = query_filter
     for arc in query.GetCompositionArcs():
-        if arc_predicate(arc):
+        if predicate(arc):
             node = arc.GetTargetNode()
             target = Usd.EditTarget(node.layerStack.identifier.rootLayer, node)
             return Usd.EditContext(prim.GetStage(), target)
-    raise ValueError(f"Could not find appropriate node for edit target for {prim} matching {arc_predicate}")
+    raise ValueError(f"Could not find appropriate node for edit target for {prim} matching {predicate}")
 
 
 @edit_context.register(Sdf.Reference)
@@ -245,8 +245,8 @@ def _(arc, /, prim: Usd.Prim) -> Usd.EditContext:
     return _edit_context_by_arc(prim, type(arc), path, layer)
 
 
-@edit_context.register(Usd.Inherits)
 @edit_context.register(Usd.Specializes)
+@edit_context.register(Usd.Inherits)
 def _(arc, /, path: Sdf.Path, layer: Sdf.Layer) -> Usd.EditContext:
     return _edit_context_by_arc(arc.GetPrim(), type(arc), path, layer)