Improve embedding docs

Author: brentyi

docs/source/embedded_visualizations.rst

@@ -14,13 +14,14 @@ Step 1: Exporting Scene State
 ----------------------------
 
 You can export static or dynamic 3D data from a Viser scene using the scene
-serializer. :func:`ViserServer.get_scene_serializer` returns a serializer
+serializer. :meth:`ViserServer.get_scene_serializer` returns a serializer
 object that can serialize the current scene state to a binary format.
 
 Static Scene Export
 ~~~~~~~~~~~~~~~~~~~
 
-For static 3D visualizations, use the following code to save the scene state:
+For static 3D visualizations, :meth:`StateSerializer.serialize` can be used to
+save the scene state:
 
 .. code-block:: python
 
@@ -40,7 +41,9 @@ For static 3D visualizations, use the following code to save the scene state:
    Path("recording.viser").write_bytes(data)
 
 
-As a suggestion, you can also add a button for exporting the scene state:
+As a suggestion, you can also add a button for exporting the scene state.
+Clicking the button in your web browser wil trigger a download of the
+``.viser`` file.
 
 .. code-block:: python
 
@@ -65,7 +68,8 @@ As a suggestion, you can also add a button for exporting the scene state:
 Dynamic Scene Export
 ~~~~~~~~~~~~~~~~~~~~
 
-For dynamic visualizations with animation, you can create a "3D video" by inserting sleep commands between frames:
+For dynamic visualizations with animation, you can create a "3D video" by
+calling :meth:`StateSerializer.insert_sleep` between frames:
 
 .. code-block:: python
 

docs/source/index.md

@@ -50,6 +50,7 @@ URL (default: `http://localhost:8080`).
    ./server.md
    ./scene_api.md
    ./gui_api.md
+   ./state_serializer.md
 
 
 .. toctree::

docs/source/state_serializer.md

@@ -0,0 +1,10 @@
+# State Serializer
+
+<!-- prettier-ignore-start -->
+
+.. autoclass:: viser.infra.StateSerializer
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+<!-- prettier-ignore-end -->

src/viser/infra/__init__.py

@@ -12,6 +12,7 @@
 """
 
 from ._infra import ClientId as ClientId
+from ._infra import StateSerializer as StateSerializer
 from ._infra import WebsockClientConnection as WebsockClientConnection
 from ._infra import WebsockMessageHandler as WebsockMessageHandler
 from ._infra import WebsockServer as WebsockServer

src/viser/infra/_infra.py

@@ -43,7 +43,7 @@ class _ClientHandleState:
 
 class StateSerializer:
     """Handle for serializing messages. In Viser, this is used to save the
-    scene state."""
+    scene state so it can be shared/embedded in static webpages."""
 
     def __init__(
         self, handler: WebsockMessageHandler, filter: Callable[[Message], bool]
@@ -63,14 +63,17 @@ def _insert_message(self, message: Message) -> None:
         self._messages.append((self._time, message.as_serializable_dict()))
 
     def insert_sleep(self, duration: float) -> None:
-        """Insert a sleep into the recorded file."""
+        """Insert a sleep into the recorded file. This can be useful for
+        dynamic 3D data."""
         assert (
             self._handler._record_handle is not None
         ), "serialize() was already called!"
         self._time += duration
 
     def serialize(self) -> bytes:
-        """Serialize saved messages. Should only be called once.
+        """Serialize saved messages. Should only be called once. Our convention
+        is to write this binary format to a file with a ``.viser`` extension,
+        for example via ``pathlib.Path("file.viser").write_bytes(...)``.
 
         Returns:
             The recording as bytes.