From b9853a95b3651dadbd776e182a88b6ac37fe7182 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 4 Jul 2026 13:24:31 +0000 Subject: [PATCH 1/6] Add interactive Python REPL playground to docs Integrate sphinx-pyrepl-web with a new Playground page that embeds a Pyodide REPL preloading grill-usd-core, grill-names, and grill. The replay session walks through the end-to-end cook workflow from the documentation examples. Also bump documented version to 0.19.1 and pin sphinx>=9 for the new extension dependency. Co-authored-by: chrizzftd --- docs/source/_static/custom.css | 6 ++++++ docs/source/conf.py | 5 +++-- docs/source/index.rst | 1 + docs/source/playground.rst | 23 +++++++++++++++++++++++ setup.cfg | 3 ++- 5 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 docs/source/playground.rst diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 686838e4..6ee30f21 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -29,3 +29,9 @@ div.xl\:hidden { max-width: none; } } + +py-repl .pyrepl, +.pyrepl { + min-height: 28rem; + width: 100%; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 65aad7bf..e419bb6d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,6 +48,7 @@ 'sphinx_inline_tabs', 'sphinx.ext.autosectionlabel', 'sphinxcontrib.doxylink', + 'sphinx_pyrepl_web', ] # Offset to play well with copybutton @@ -101,9 +102,9 @@ # built documents. # # The short X.Y version. -version = '0.18' +version = '0.19' # The full version, including alpha/beta/rc tags. -release = '0.18.0' +release = '0.19.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/index.rst b/docs/source/index.rst index b59e22a7..3ed393a3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,6 +17,7 @@ pipeline views end_to_end + playground api Indices and tables diff --git a/docs/source/playground.rst b/docs/source/playground.rst new file mode 100644 index 00000000..fce968c3 --- /dev/null +++ b/docs/source/playground.rst @@ -0,0 +1,23 @@ +Playground +========== + +Try ``grill.cook`` and ``grill.names`` in your browser. Packages are loaded via Pyodide; USD comes from the experimental ``grill-usd-core`` WASM build. + +.. attention:: + + This REPL is experimental. Asset creation writes to a temporary in-browser filesystem that is lost on refresh. + +.. py-repl:: + :packages: grill-usd-core==26.8, grill-names>=2.6.0, grill==0.19.1 + :repl-title: Grill Cook Playground + :theme: catppuccin-latte + :no-banner: + + >>> from grill import cook, names + >>> import tempfile + >>> from pathlib import Path + >>> cook.Repository.set(Path(tempfile.mkdtemp())) + >>> stage = cook.fetch_stage(cook.UsdAsset.get_anonymous()) + >>> character = cook.define_taxon(stage, "Character") + >>> character + >>> cook.create_unit(character, "Hero01", label="Hero 01") diff --git a/setup.cfg b/setup.cfg index 38e4ba8b..eb065917 100644 --- a/setup.cfg +++ b/setup.cfg @@ -52,7 +52,8 @@ include = grill.* # python -m pip install -e . docs = - sphinx + sphinx>=9,<10 + sphinx-pyrepl-web>=0.2.0 myst-parser sphinx-toggleprompt sphinx-copybutton From 49e3acb395553cc05547a0db3f33348153b4a746 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 4 Jul 2026 13:39:01 +0000 Subject: [PATCH 2/6] Use default pyrepl theme on playground page Co-authored-by: chrizzftd --- docs/source/playground.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/playground.rst b/docs/source/playground.rst index fce968c3..465b29ab 100644 --- a/docs/source/playground.rst +++ b/docs/source/playground.rst @@ -10,7 +10,6 @@ Try ``grill.cook`` and ``grill.names`` in your browser. Packages are loaded via .. py-repl:: :packages: grill-usd-core==26.8, grill-names>=2.6.0, grill==0.19.1 :repl-title: Grill Cook Playground - :theme: catppuccin-latte :no-banner: >>> from grill import cook, names From 56cd3cff60e9fea7cf73f1fcd2a1173511e4df18 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 7 Jul 2026 14:38:25 +0000 Subject: [PATCH 3/6] Upgrade sphinx-pyrepl-web to 0.4.0 with autodoc REPLs Enable interactive doctest REPLs on API pages via the :project: sentinel, which auto-builds the grill wheel at doc-build time. Augment resolved packages with grill-usd-core and grill-names for browser WASM compatibility. Follows sphinx-pyrepl-web PR #25 and grill-names PR #35 patterns. Co-authored-by: chrizzftd --- .gitignore | 1 + docs/source/_static/wheels/.gitkeep | 0 docs/source/conf.py | 16 ++++++++++++++++ setup.cfg | 2 +- 4 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/wheels/.gitkeep diff --git a/.gitignore b/.gitignore index d8cf321a..36a82bf8 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,6 @@ dist/ build/ grill.egg-info/ docs/build/ +docs/source/_static/wheels/*.whl docs/Makefile docs/make.bat diff --git a/docs/source/_static/wheels/.gitkeep b/docs/source/_static/wheels/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/conf.py b/docs/source/conf.py index e419bb6d..20899b73 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -147,6 +147,10 @@ 'custom.css', ] +pyrepl_doctest_blocks = "autodoc" +pyrepl_autodoc_packages = ":project:" +pyrepl_project_root = "../.." + # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. @@ -315,8 +319,20 @@ def _find_doxygen_link_with_title(name, rawtext, text, *patched_args, **patched_ _doxylink_ext.create_role = _create_doxylink_role_with_title +def _augment_pyrepl_packages(app): + """Append WASM USD and grill-names to the auto-built project wheel.""" + try: + wheel = object.__getattribute__(app, "_pyrepl_resolved_autodoc_packages") + except AttributeError: + return + app._pyrepl_resolved_autodoc_packages = ( + "grill-usd-core==26.8, grill-names>=2.6.0, " + wheel + ) + + 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) + app.connect("builder-inited", _augment_pyrepl_packages, priority=500) return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/setup.cfg b/setup.cfg index eb065917..d07dcfb7 100644 --- a/setup.cfg +++ b/setup.cfg @@ -53,7 +53,7 @@ include = grill.* docs = sphinx>=9,<10 - sphinx-pyrepl-web>=0.2.0 + sphinx-pyrepl-web>=0.4.0 myst-parser sphinx-toggleprompt sphinx-copybutton From d1a29890c726791de3873eeaed322ecff242f147 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 7 Jul 2026 21:23:59 +0000 Subject: [PATCH 4/6] Remove pyrepl CSS workaround and autodoc package augmentation hook Drop custom REPL sizing rules and the _augment_pyrepl_packages conf.py hook; extra autodoc package deps should be handled upstream in sphinx-pyrepl-web. Co-authored-by: chrizzftd --- docs/source/_static/custom.css | 6 ------ docs/source/conf.py | 12 ------------ 2 files changed, 18 deletions(-) diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 6ee30f21..686838e4 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -29,9 +29,3 @@ div.xl\:hidden { max-width: none; } } - -py-repl .pyrepl, -.pyrepl { - min-height: 28rem; - width: 100%; -} diff --git a/docs/source/conf.py b/docs/source/conf.py index 20899b73..f1824ace 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -319,20 +319,8 @@ def _find_doxygen_link_with_title(name, rawtext, text, *patched_args, **patched_ _doxylink_ext.create_role = _create_doxylink_role_with_title -def _augment_pyrepl_packages(app): - """Append WASM USD and grill-names to the auto-built project wheel.""" - try: - wheel = object.__getattribute__(app, "_pyrepl_resolved_autodoc_packages") - except AttributeError: - return - app._pyrepl_resolved_autodoc_packages = ( - "grill-usd-core==26.8, grill-names>=2.6.0, " + wheel - ) - - 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) - app.connect("builder-inited", _augment_pyrepl_packages, priority=500) return {"parallel_read_safe": True, "parallel_write_safe": True} From 353585d71bb8b3eb9ac3ac43cc8a2b4605f021c6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 7 Jul 2026 21:57:10 +0000 Subject: [PATCH 5/6] QC sphinx-pyrepl-web PR #26 comma-separated :project: packages Pin docs extra to the PR branch and use combined package specs for autodoc REPLs and the playground directive, replacing the removed conf.py augmentation hook and pinned PyPI grill version. Validated: docs build succeeds; playground and api.html emit REPLs preloading the auto-built grill wheel plus grill-usd-core and grill-names. Co-authored-by: chrizzftd --- docs/source/conf.py | 2 +- docs/source/playground.rst | 2 +- setup.cfg | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f1824ace..ac51fdcb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -148,7 +148,7 @@ ] pyrepl_doctest_blocks = "autodoc" -pyrepl_autodoc_packages = ":project:" +pyrepl_autodoc_packages = ":project:,grill-usd-core==26.8,grill-names>=2.6.0" pyrepl_project_root = "../.." # -- Options for HTMLHelp output ------------------------------------------ diff --git a/docs/source/playground.rst b/docs/source/playground.rst index 465b29ab..904a1103 100644 --- a/docs/source/playground.rst +++ b/docs/source/playground.rst @@ -8,7 +8,7 @@ Try ``grill.cook`` and ``grill.names`` in your browser. Packages are loaded via This REPL is experimental. Asset creation writes to a temporary in-browser filesystem that is lost on refresh. .. py-repl:: - :packages: grill-usd-core==26.8, grill-names>=2.6.0, grill==0.19.1 + :packages: :project:,grill-usd-core==26.8,grill-names>=2.6.0 :repl-title: Grill Cook Playground :no-banner: diff --git a/setup.cfg b/setup.cfg index d07dcfb7..0fcc4537 100644 --- a/setup.cfg +++ b/setup.cfg @@ -53,7 +53,7 @@ include = grill.* docs = sphinx>=9,<10 - sphinx-pyrepl-web>=0.4.0 + sphinx-pyrepl-web @ git+https://github.com/chrizzFTD/sphinx-pyrepl-web.git@cursor/project-package-lists-370c myst-parser sphinx-toggleprompt sphinx-copybutton From a2bc515dd07722046b3dc3555340b163cfd93638 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 8 Jul 2026 08:26:31 +0000 Subject: [PATCH 6/6] Remove redundant pyrepl_project_root from conf.py Project root is auto-detected by walking up from docs/source/ to the repo root (setup.cfg). Explicit override was unnecessary. Co-authored-by: chrizzftd --- docs/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ac51fdcb..dddf5e64 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -149,7 +149,6 @@ pyrepl_doctest_blocks = "autodoc" pyrepl_autodoc_packages = ":project:,grill-usd-core==26.8,grill-names>=2.6.0" -pyrepl_project_root = "../.." # -- Options for HTMLHelp output ------------------------------------------