NF: Add Jupyter notebook widget for WebGL viewer

[mvdoc]

Summary

Add cortex.webgl.jupyter module for embedding the WebGL brain viewer in Jupyter notebooks:

• display(data) — IFrame mode: starts Tornado server in background thread, embeds via IFrame. Full interactivity with WebSocket/JSMixer control.
• display(data, method="static") — Static mode: generates self-contained viewer directory served via local HTTP server. Returns StaticViewer handle with close() for cleanup.
• make_notebook_html(data) — returns raw HTML string for custom embedding.
• Reliable port selection via socket.bind(('', 0)) instead of random.randint
• StaticViewer class with:
  • Proper resource cleanup (HTTP server shutdown + temp dir removal)
  • Public closed property
  • Context manager protocol (with viewer:)
  • _repr_html_() that shows "closed" message after cleanup
  • Automatic removal from active viewer registry on close
• IFrame URL uses 127.0.0.1 by default (configurable via CORTEX_JUPYTER_IFRAME_HOST and CORTEX_JUPYTER_STATIC_HOST env vars for remote setups)
• Resource leak protection: HTTP server and temp files cleaned up even if ipydisplay() or HTTPServer() fails
• close_all() releases lock before blocking shutdown to prevent deadlocks; hardened for interpreter teardown
• Thread join timeout warnings logged when server thread doesn't stop
• nbsphinx guarded with try/except in docs config so local builds work without it
• 44 unit tests covering dispatch, port handling, lifecycle, cleanup, error paths, resource leaks, and lock safety

New/modified files

• cortex/webgl/jupyter.py — main module
• cortex/webgl/__init__.py — guarded import of jupyter submodule
• cortex/tests/test_jupyter_widget.py — 44 tests
• docs/notebooks/jupyter_notebook.ipynb — example notebook (auto-executed at docs build time)
• docs/conf.py — optional nbsphinx integration

Test plan

• python -m pytest cortex/tests/test_jupyter_widget.py -v — 44 tests pass
• Verify notebook executes via jupyter nbconvert --execute
• Test display(vol) in live Jupyter notebook
• Test display(vol, method="static") in live Jupyter notebook
• Test viewer.close() cleans up server and temp files
• Test context manager (with viewer:) auto-cleanup
• Test close_all() cleans up multiple viewers
• Verify docs/conf.py works with and without nbsphinx installed

[mvdoc]

The goal is to have something like this in a jupyter notebook. The widgets should allow that (need to test it)

(This is another one of those "I wonder if Claude can do it" things coded on my phone)

[Copilot]

Pull request overview

This PR adds first-class Jupyter notebook support for embedding the cortex.webgl viewer, along with documentation and CI updates to build/render an example notebook in the Sphinx docs.

Changes:

• Add cortex.webgl.jupyter with display() dispatch plus iframe/static helpers and a StaticViewer lifecycle handle.
• Add a notebook-optimized WebGL HTML template and an example executed notebook in the docs.
• Update docs build configuration and workflows to support rendering notebooks (nbsphinx + dependencies).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
cortex/webgl/jupyter.py	New Jupyter integration module (iframe/static display + HTML generation helpers).
cortex/webgl/notebook.html	New HTML template variant tailored for notebook iframe usage.
cortex/webgl/__init__.py	Exposes cortex.webgl.jupyter when IPython is available.
cortex/tests/test_jupyter_widget.py	Adds unit tests for dispatch, port selection, and static viewer lifecycle.
docs/notebooks/jupyter_notebook.ipynb	New example notebook demonstrating usage.
docs/notebooks/.gitignore	Ignores artifacts generated during notebook execution.
docs/index.rst	Adds the notebook page to the docs toctree.
docs/conf.py	Conditionally enables nbsphinx and copies notebook artifacts into build output.
.github/workflows/build_docs.yml	Installs pandoc/nbsphinx/ipykernel and builds docs in CI.
docs/.github/workflows/build_docs.yml	Adds a second (duplicate) docs workflow under docs/ (note: not a standard Actions location).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

HTML is imported from IPython.display but never used in this module. This adds an unnecessary hard dependency at import-time and may trigger unused-import checks in downstream tooling; please remove it or use it.

Suggested change

	from IPython.display import HTML, IFrame
	from IPython.display import IFrame

[Copilot]

StaticViewer.close() only calls HTTPServer.shutdown() but never calls server_close() and never joins the serving thread. This can leave the listening socket open longer than intended and makes cleanup less reliable; consider making close() idempotent, calling shutdown() + server_close(), and joining the thread with a short timeout.

Suggested change

	def close(self):
	"""Shut down the HTTP server and remove temp files."""
	try:
	self._httpd.shutdown()
	except Exception:
	logger.warning("Failed to shut down static viewer server", exc_info=True)
	try:
	shutil.rmtree(self._tmpdir, ignore_errors=True)
	except Exception:
	logger.warning(
	"Failed to clean up temp dir %s", self._tmpdir, exc_info=True
	)
	def __del__(self):
	try:
	self._httpd.shutdown()
	except Exception:
	pass
	try:
	shutil.rmtree(self._tmpdir, ignore_errors=True)
	except Exception:
	pass
	# Track shutdown state to make close() idempotent and thread-safe.
	self._closed = False
	self._lock = threading.Lock()
	def close(self, timeout=1.0):
	"""Shut down the HTTP server, wait for the thread, and remove temp files.
	Parameters
	----------
	timeout : float, optional
	Maximum number of seconds to wait for the server thread to finish.
	"""
	# Ensure idempotent, thread-safe shutdown.
	try:
	lock = self._lock
	except AttributeError:
	# If attributes are partially initialized or being torn down,
	# fall back to best-effort cleanup without synchronization.
	lock = None
	if lock is not None:
	with lock:
	if getattr(self, "_closed", False):
	return
	self._closed = True
	else:
	if getattr(self, "_closed", False):
	return
	self._closed = True
	# Stop the HTTP server and close its listening socket.
	httpd = getattr(self, "_httpd", None)
	if httpd is not None:
	try:
	httpd.shutdown()
	httpd.server_close()
	except Exception:
	logger.warning(
	"Failed to shut down static viewer server",
	exc_info=True,
	)
	# Give the serving thread a chance to exit cleanly.
	thread = getattr(self, "_thread", None)
	if thread is not None and thread.is_alive():
	try:
	thread.join(timeout=timeout)
	except Exception:
	logger.warning(
	"Failed to join static viewer server thread",
	exc_info=True,
	)
	# Finally, remove the temporary directory.
	tmpdir = getattr(self, "_tmpdir", None)
	if tmpdir is not None:
	try:
	shutil.rmtree(tmpdir, ignore_errors=True)
	except Exception:
	logger.warning(
	"Failed to clean up temp dir %s", tmpdir, exc_info=True
	)
	def __del__(self):
	# Best-effort cleanup during garbage collection; avoid raising.
	try:
	self.close(timeout=0.1)
	except Exception:
	pass

[Copilot]

The module docstring example says cortex.webgl.jupyter.display(vol) “auto-detects best approach”, but display() defaults to method="iframe" and does not perform any auto-detection. Please update the docstring/example to match the actual behavior (or implement auto-detection if that’s intended).