From 6d8d3c29e60c89823426c7e4fd5f969fadcc401b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Sun, 22 Dec 2024 08:55:37 +1100 Subject: [PATCH] fix malformed iprims formatted signature MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian López Barrón --- docs/source/conf.py | 27 ++++++++++++++++++++------- grill/usd/__init__.py | 10 ++++------ 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6bf2bd67..111ad1d0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,6 +20,7 @@ # import os # import sys # sys.path.insert(0, os.path.abspath('.')) +import functools from datetime import datetime # -- General configuration ------------------------------------------------ @@ -240,25 +241,29 @@ # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] -_USD_DOXYGEN_TAG_URL = "https://openusd.org/release/USD.tag" _USD_DOXYGEN_CACHE_NAME = 'usdcpp' _USD_DOXYGEN_ROOT_DIR = "https://openusd.org/release/api/" doxylink = { - _USD_DOXYGEN_CACHE_NAME: (_USD_DOXYGEN_TAG_URL, _USD_DOXYGEN_ROOT_DIR) + _USD_DOXYGEN_CACHE_NAME: ("https://openusd.org/release/USD.tag", _USD_DOXYGEN_ROOT_DIR) } + def _handle_missing_usd_reference(app, env, node, contnode): """Handle missing references by redirecting to a custom URL.""" from docutils import nodes - from sphinxcontrib.doxylink import doxylink target = node['reftarget'] if not target.startswith('pxr.'): return None + full_url = _get_url_for_target(app, target) + return nodes.reference('', contnode.astext(), refuri=full_url) + + +@functools.cache +def _get_url_for_target(app, target): + from sphinxcontrib.doxylink import doxylink pxr_obj_namespace = target.removeprefix('pxr.').replace(".", "") - print(f"{target=}") - print(f"{pxr_obj_namespace=}") pxr_obj_namespace = { "UsdInitialLoadSet": "UsdStage::InitialLoadSet", # there's a level of indirection in the python bindings? "UsdFilter": "UsdPrimCompositionQuery::Filter", # filter is a member of the query type @@ -270,11 +275,19 @@ def _handle_missing_usd_reference(app, env, node, contnode): part = doxylink.utils.unescape(part) url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part] full_url = doxylink.join(_USD_DOXYGEN_ROOT_DIR, url.file) - print(full_url) - return nodes.reference('', contnode.astext(), refuri=full_url) + return full_url + + +def _grill_process_signature(app, what, name, obj, options, signature, return_annotation): + if name == "grill.usd.iprims": # Target the specific function + # Prim predicates don't have a __repr__, which creates malformed signature formatting (no new lines, no links) + # Report to pixar + signature = signature.replace("", "Usd.PrimDefaultPredicate") + 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} diff --git a/grill/usd/__init__.py b/grill/usd/__init__.py index 97119702..8acd46a1 100644 --- a/grill/usd/__init__.py +++ b/grill/usd/__init__.py @@ -61,14 +61,12 @@ def common_paths(paths: abc.Iterable[Sdf.Path]) -> list[Sdf.Path]: def iprims(stage: Usd.Stage, root_paths: abc.Iterable[Sdf.Path] = tuple(), prune_predicate: abc.Callable[[Usd.Prim], bool] = None, traverse_predicate: typing.Union[Usd._Term, Usd._PrimFlagsConjunction] = Usd.PrimDefaultPredicate) -> abc.Iterator[Usd.Prim]: """Convenience function that creates an iterator useful for common :ref:`glossary:stage traversal`. - Refer to the :ref:`glossary:specifier` ins the documentation. - Refer to the :ref:`Specifier ` in the documentation. + 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. - Without keyword arguments, this is the same as calling `Usd.Stage.Traverse(...)`, so - use that instead when no `root_paths` or `prune_predicates` are needed. + A :usdcpp:`UsdPrimRange` with the provided ``traverse_predicate`` is created for each :usdcpp:`SdfPath` in ``root_paths``, + for which :usdcpp:`PruneChildren ` is called whenever a traversed :usdcpp:`Prim ` passes ``prune_predicate``. - The remaining methods - (e.g. :code:`GetChildren()`) all use a predefined :usdcpp:`Default Predicate ` """ if root_paths: # Traverse only specific parts of the stage. root_paths = common_paths(root_paths)