Update docs related to notebook (rerun-io#1915)

* Update docs related to notebook * Add actual args to show to improve docs
luxonis · Apr 18, 2023 · e3b09af · e3b09af
1 parent 26ac168
commit e3b09af
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 13 deletions.
diff --git a/rerun_py/docs/gen_common_index.py b/rerun_py/docs/gen_common_index.py
@@ -49,7 +49,7 @@ class Section:
     Section(
         title="Initialization",
         module_summary=None,
-        func_list=["init", "connect", "disconnect", "spawn", "serve"],
+        func_list=["init", "connect", "disconnect", "spawn", "serve", "memory_recording"],
     ),
     Section(
         title="Viewer Control",

diff --git a/rerun_py/mkdocs.yml b/rerun_py/mkdocs.yml
@@ -25,6 +25,7 @@ plugins:
           import: # Cross-references for python and numpy
             - https://docs.python.org/3/objects.inv
             - https://numpy.org/doc/stable/objects.inv
+            - https://ipython.readthedocs.io/en/stable/objects.inv
           options: # https://mkdocstrings.github.io/python/usage/#globallocal-options
             show_source: no
             docstring_style: numpy

diff --git a/rerun_py/rerun_sdk/rerun/__init__.py b/rerun_py/rerun_sdk/rerun/__init__.py
@@ -423,6 +423,9 @@ def memory_recording() -> MemoryRecording:
     """
     Streams all log-data to a memory buffer.
 
+    This can be used to display the RRD to alternative formats such as html.
+    See: [rerun.MemoryRecording.as_html][].
+
     Returns
     -------
     MemoryRecording

diff --git a/rerun_py/rerun_sdk/rerun/recording.py b/rerun_py/rerun_sdk/rerun/recording.py
@@ -1,4 +1,4 @@
-"""Helper functions for displaying Rerun in a Jupyter notebook."""
+"""Helper functions for directly working with recordings."""
 
 import base64
 import logging
@@ -8,31 +8,42 @@
 
 from rerun import bindings
 
+DEFAULT_WIDTH = 950
+DEFAULT_HEIGHT = 712
+DEFAULT_TIMEOUT = 2000
+
 
 class MemoryRecording:
     def __init__(self, storage: bindings.PyMemorySinkStorage) -> None:
         self.storage = storage
 
     def as_html(
-        self, width: int = 950, height: int = 712, app_location: Optional[str] = None, timeout_ms: int = 2000
+        self,
+        width: int = DEFAULT_WIDTH,
+        height: int = DEFAULT_HEIGHT,
+        app_url: Optional[str] = None,
+        timeout_ms: int = DEFAULT_TIMEOUT,
     ) -> str:
         """
-        Show the Rerun viewer in a Jupyter notebook.
+        Generate an HTML snippet that displays the recording in an IFrame.
+
+        For use in contexts such as Jupyter notebooks.
 
         Parameters
         ----------
         width : int
             The width of the viewer in pixels.
         height : int
             The height of the viewer in pixels.
-        app_location : str
-            The location of the Rerun web viewer.
+        app_url : str
+            Alternative HTTP url to find the Rerun web viewer. This will default to using https://app.rerun.io
+            or localhost if [rerun.start_web_viewer_server][] has been called.
         timeout_ms : int
             The number of milliseconds to wait for the Rerun web viewer to load.
         """
 
-        if app_location is None:
-            app_location = bindings.get_app_url()
+        if app_url is None:
+            app_url = bindings.get_app_url()
 
         # Use a random presentation ID to avoid collisions when multiple recordings are shown in the same notebook.
         presentation_id = "".join(random.choice(string.ascii_letters) for i in range(6))
@@ -41,8 +52,8 @@ def as_html(
 
         html_template = f"""
         <div id="{presentation_id}_rrd" style="display: none;" data-rrd="{base64_data}"></div>
-        <div id="{presentation_id}_error" style="display: none;"><p>Timed out waiting for {app_location} to load.</p>
-        <p>Consider using <code>rr.self_host_assets()</code></p></div>
+        <div id="{presentation_id}_error" style="display: none;"><p>Timed out waiting for {app_url} to load.</p>
+        <p>Consider using <code>rr.start_web_viewer_server()</code></p></div>
         <script>
             {presentation_id}_timeout = setTimeout(() => {{
                 document.getElementById("{presentation_id}_error").style.display = 'block';
@@ -72,14 +83,35 @@ def as_html(
             }}()));
         </script>
         <iframe id="{presentation_id}_iframe" width="{width}" height="{height}"
-            src="{app_location}?url=web_event://&persist=0"
+            src="{app_url}?url=web_event://&persist=0"
             frameborder="0" style="display: none;" allowfullscreen=""></iframe>
         """
 
         return html_template
 
-    def show(self, **kwargs: Any) -> Any:
-        html = self.as_html(**kwargs)
+    def show(
+        self,
+        width: int = DEFAULT_WIDTH,
+        height: int = DEFAULT_HEIGHT,
+        app_url: Optional[str] = None,
+        timeout_ms: int = DEFAULT_TIMEOUT,
+    ) -> Any:
+        """
+        Output the Rerun viewer using IPython [IPython.core.display.HTML][].
+
+        Parameters
+        ----------
+        width : int
+            The width of the viewer in pixels.
+        height : int
+            The height of the viewer in pixels.
+        app_url : str
+            Alternative HTTP url to find the Rerun web viewer. This will default to using https://app.rerun.io
+            or localhost if [rerun.start_web_viewer_server][] has been called.
+        timeout_ms : int
+            The number of milliseconds to wait for the Rerun web viewer to load.
+        """
+        html = self.as_html(width=width, height=height, app_url=app_url, timeout_ms=timeout_ms)
         try:
             from IPython.core.display import HTML