From 81cb02b2f91ced9ff63099009baf6c6bd1e8c401 Mon Sep 17 00:00:00 2001
From: brentyi <yibrenth@gmail.com>
Date: Sun, 5 Jan 2025 15:32:46 -0800
Subject: [PATCH] Improve embedding docs

---
 docs/source/embedded_visualizations.rst | 12 ++++++++----
 docs/source/index.md                    |  1 +
 docs/source/state_serializer.md         | 10 ++++++++++
 src/viser/infra/__init__.py             |  1 +
 src/viser/infra/_infra.py               |  9 ++++++---
 5 files changed, 26 insertions(+), 7 deletions(-)
 create mode 100644 docs/source/state_serializer.md

diff --git a/docs/source/embedded_visualizations.rst b/docs/source/embedded_visualizations.rst
index 0cfda5aa9..d096b8ebe 100644
--- a/docs/source/embedded_visualizations.rst
+++ b/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
 
diff --git a/docs/source/index.md b/docs/source/index.md
index 632f91424..bf8c99b57 100644
--- a/docs/source/index.md
+++ b/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::
diff --git a/docs/source/state_serializer.md b/docs/source/state_serializer.md
new file mode 100644
index 000000000..e665663f1
--- /dev/null
+++ b/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 -->
diff --git a/src/viser/infra/__init__.py b/src/viser/infra/__init__.py
index 57171dfa3..ae0a328ed 100644
--- a/src/viser/infra/__init__.py
+++ b/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
diff --git a/src/viser/infra/_infra.py b/src/viser/infra/_infra.py
index 6738adff5..20e9c0d19 100644
--- a/src/viser/infra/_infra.py
+++ b/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.