From e3b09af9d0db949b8ff3bb8fea8a5c3e364fb104 Mon Sep 17 00:00:00 2001 From: Jeremy Leibs Date: Tue, 18 Apr 2023 17:46:12 -0400 Subject: [PATCH] Update docs related to notebook (#1915) * Update docs related to notebook * Add actual args to show to improve docs --- rerun_py/docs/gen_common_index.py | 2 +- rerun_py/mkdocs.yml | 1 + rerun_py/rerun_sdk/rerun/__init__.py | 3 ++ rerun_py/rerun_sdk/rerun/recording.py | 56 +++++++++++++++++++++------ 4 files changed, 49 insertions(+), 13 deletions(-) diff --git a/rerun_py/docs/gen_common_index.py b/rerun_py/docs/gen_common_index.py index a63dc77f62a8..b159a49858bd 100644 --- 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 index 1a2a6af3cbf1..9122a734af4b 100644 --- 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 index 3674fa642291..799ec2ccfd50 100644 --- 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 index 428da607735c..efe9b7b25bea 100644 --- 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,16 +8,26 @@ 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 ---------- @@ -25,14 +35,15 @@ def as_html( 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""" - + """ 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