From 82f3c3e4fe22b34403bdd31e90dcacbfa7c95397 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Sun, 7 Jun 2026 11:27:08 +1000 Subject: [PATCH 1/6] Pin Sphinx below 9 for RTD docs builds. sphinx-hoverxref is incompatible with Sphinx 9's config API, which broke Read the Docs builds that installed the latest unpinned Sphinx release. Co-authored-by: Cursor --- setup.cfg | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 6a2deb9b..1dddb015 100644 --- a/setup.cfg +++ b/setup.cfg @@ -49,6 +49,17 @@ include = grill.* # To install packages in editable mode, cd to desired package repo, then: # python -m pip install -e . -docs = sphinx; myst-parser; sphinx-toggleprompt; sphinx-copybutton; sphinx-togglebutton; sphinx-hoverxref>=1.4.1; sphinx_autodoc_typehints; sphinx-inline-tabs; shibuya; usd-core; sphinxcontrib-doxylink +docs = + sphinx>=7.2,<9 + myst-parser + sphinx-toggleprompt + sphinx-copybutton + sphinx-togglebutton + sphinx-hoverxref>=1.4.1,<2 + sphinx_autodoc_typehints + sphinx-inline-tabs + shibuya + usd-core + sphinxcontrib-doxylink full = PySide6; usd-core; PyOpenGL create = grill-names>=2.6.0 From 7335816c5af21d5bdd458329506540aade37ce29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Sun, 7 Jun 2026 11:39:03 +1000 Subject: [PATCH 2/6] Fix doxylink aliases for nested PrimCompositionQuery Python types. Autodoc resolves pxr.Usd.PrimCompositionQuery.Filter to UsdPrimCompositionQueryFilter, which was not in the C++ name mapping and crashed RTD builds during api.rst output. Co-authored-by: Cursor --- docs/source/conf.py | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9437f877..6255f503 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -266,13 +266,22 @@ def _get_url_for_usd_target(app, target): pxr_obj_namespace = target.removeprefix('pxr.').replace(".", "") pxr_obj_namespace = { "UsdInitialLoadSet": "UsdStage::InitialLoadSet", # there's indirection in the python bindings - "UsdFilter": "UsdPrimCompositionQuery::Filter", # filter is a member of the query type + # nested PrimCompositionQuery types (pxr.Usd.PrimCompositionQuery.* -> UsdPrimCompositionQuery*) + "UsdPrimCompositionQueryFilter": "UsdPrimCompositionQuery::Filter", + "UsdPrimCompositionQueryDependencyTypeFilter": "UsdPrimCompositionQuery::DependencyTypeFilter", + "UsdPrimCompositionQueryArcTypeFilter": "UsdPrimCompositionQuery::ArcTypeFilter", + "UsdPrimCompositionQueryArcIntroducedFilter": "UsdPrimCompositionQuery::ArcIntroducedFilter", + "UsdPrimCompositionQueryHasSpecsFilter": "UsdPrimCompositionQuery::HasSpecsFilter", + "UsdFilter": "UsdPrimCompositionQuery::Filter", # legacy alias "UsdCompositionArc": "UsdPrimCompositionQueryArc", "Usd_Term": "primFlags.h", "Usd_PrimFlagsConjunction": "primFlags.h", }.get(pxr_obj_namespace, pxr_obj_namespace) part = _get_doxylink_part(pxr_obj_namespace) - url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part] + try: + url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part] + except LookupError: + return None full_url = _doxylink_ext.join(_USD_DOXYGEN_ROOT_DIR, url.file) reftitle = _get_usd_ref_tooltip(app) return part + " " + reftitle, full_url @@ -282,8 +291,9 @@ def _handle_missing_usd_reference(app, env, node, contnode): from docutils import nodes if (target := node['reftarget']).startswith('pxr.'): - reftitle, refuri = _get_url_for_usd_target(app, target) - return nodes.reference('', contnode.astext(), internal=False, refuri=refuri, reftitle=reftitle) + if result := _get_url_for_usd_target(app, target): + reftitle, refuri = result + return nodes.reference('', contnode.astext(), internal=False, refuri=refuri, reftitle=reftitle) def _grill_process_signature(app, what, name, obj, options, signature, return_annotation): From 691c00ea40ffcdc62d154c65fc3a1a7399d4da66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Sun, 7 Jun 2026 12:11:02 +1000 Subject: [PATCH 3/6] keep raising when doxylink fails 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 | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6255f503..8b5ba0be 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -278,10 +278,7 @@ def _get_url_for_usd_target(app, target): "Usd_PrimFlagsConjunction": "primFlags.h", }.get(pxr_obj_namespace, pxr_obj_namespace) part = _get_doxylink_part(pxr_obj_namespace) - try: - url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part] - except LookupError: - return None + url = app.env.doxylink_cache[_USD_DOXYGEN_CACHE_NAME]['mapping'][part] full_url = _doxylink_ext.join(_USD_DOXYGEN_ROOT_DIR, url.file) reftitle = _get_usd_ref_tooltip(app) return part + " " + reftitle, full_url @@ -291,9 +288,8 @@ def _handle_missing_usd_reference(app, env, node, contnode): from docutils import nodes if (target := node['reftarget']).startswith('pxr.'): - if result := _get_url_for_usd_target(app, target): - reftitle, refuri = result - return nodes.reference('', contnode.astext(), internal=False, refuri=refuri, reftitle=reftitle) + reftitle, refuri = _get_url_for_usd_target(app, target) + return nodes.reference('', contnode.astext(), internal=False, refuri=refuri, reftitle=reftitle) def _grill_process_signature(app, what, name, obj, options, signature, return_annotation): From 651ba001b4b5d460ece6c4daec020a133f1aa0b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Sun, 7 Jun 2026 12:54:49 +1000 Subject: [PATCH 4/6] Add doxylink alias for pxr.Usd.Stage.InitialLoadSet. Autodoc normalizes the nested enum to UsdStageInitialLoadSet, which was not covered by the legacy UsdInitialLoadSet mapping used by fetch_stage signatures. Co-authored-by: Cursor --- docs/source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8b5ba0be..b84670c0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -265,7 +265,8 @@ def _get_usd_ref_tooltip(app): def _get_url_for_usd_target(app, target): pxr_obj_namespace = target.removeprefix('pxr.').replace(".", "") pxr_obj_namespace = { - "UsdInitialLoadSet": "UsdStage::InitialLoadSet", # there's indirection in the python bindings + "UsdStageInitialLoadSet": "UsdStage::InitialLoadSet", # pxr.Usd.Stage.InitialLoadSet + "UsdInitialLoadSet": "UsdStage::InitialLoadSet", # legacy alias # nested PrimCompositionQuery types (pxr.Usd.PrimCompositionQuery.* -> UsdPrimCompositionQuery*) "UsdPrimCompositionQueryFilter": "UsdPrimCompositionQuery::Filter", "UsdPrimCompositionQueryDependencyTypeFilter": "UsdPrimCompositionQuery::DependencyTypeFilter", From 0d7723670050a565078ebbfdf1de0d339df9daee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Mon, 8 Jun 2026 10:30:28 +1000 Subject: [PATCH 5/6] update doc env snippet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christian López Barrón --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 1dddb015..6f56714a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -43,7 +43,7 @@ include = grill.* # conda install conda-forge::graphviz=11 # 13.1.2 brings up libffi which messes up _ctypes from python-3.13, and 12 fails to load gvplugin_pango.dll # python -m pip install grill-names>=2.6.0 networkx>=3.4 pydot>=3.0.1 numpy PyOpenGL pyside6 # docs dependencies: -# python -m pip install sphinx myst-parser sphinx-toggleprompt sphinx-copybutton sphinx-togglebutton sphinx-hoverxref>=1.4.1 sphinx_autodoc_typehints sphinx-inline-tabs shibuya sphinxcontrib-doxylink +# python -m pip install -U "sphinx>=7.2,<9" myst-parser sphinx-toggleprompt sphinx-copybutton sphinx-togglebutton "sphinx-hoverxref>=1.4.1" sphinx_autodoc_typehints sphinx-inline-tabs shibuya sphinxcontrib-doxylink # For EDGEDB (coming up) # python -m pip install edgedb # To install packages in editable mode, cd to desired package repo, then: From 74849800a707a335274bff9a18f71df1b96a8309 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=B3pez=20Barr=C3=B3n?= Date: Mon, 8 Jun 2026 10:31:12 +1000 Subject: [PATCH 6/6] cleanup unneeded doxylunk namespace mapping entries and added comment for when to add new ones 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 | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b84670c0..f8a4d932 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -264,16 +264,13 @@ def _get_usd_ref_tooltip(app): @functools.cache def _get_url_for_usd_target(app, target): pxr_obj_namespace = target.removeprefix('pxr.').replace(".", "") + # Some doxylink urls from python binding members not map directly yet. + # Add entries here for exceptions such as: LookupError: No documentation entry matching "UsdStageInitialLoadSet" + # Enclosed as: + # sphinx.errors.ExtensionError: Handler for event 'missing-reference' threw an exception (exception: No documentation entry matching "UsdStageInitialLoadSet") pxr_obj_namespace = { - "UsdStageInitialLoadSet": "UsdStage::InitialLoadSet", # pxr.Usd.Stage.InitialLoadSet - "UsdInitialLoadSet": "UsdStage::InitialLoadSet", # legacy alias - # nested PrimCompositionQuery types (pxr.Usd.PrimCompositionQuery.* -> UsdPrimCompositionQuery*) + "UsdStageInitialLoadSet": "UsdStage::InitialLoadSet", "UsdPrimCompositionQueryFilter": "UsdPrimCompositionQuery::Filter", - "UsdPrimCompositionQueryDependencyTypeFilter": "UsdPrimCompositionQuery::DependencyTypeFilter", - "UsdPrimCompositionQueryArcTypeFilter": "UsdPrimCompositionQuery::ArcTypeFilter", - "UsdPrimCompositionQueryArcIntroducedFilter": "UsdPrimCompositionQuery::ArcIntroducedFilter", - "UsdPrimCompositionQueryHasSpecsFilter": "UsdPrimCompositionQuery::HasSpecsFilter", - "UsdFilter": "UsdPrimCompositionQuery::Filter", # legacy alias "UsdCompositionArc": "UsdPrimCompositionQueryArc", "Usd_Term": "primFlags.h", "Usd_PrimFlagsConjunction": "primFlags.h",