Skip to content

Commit

Permalink
Docs + aesthetics
Browse files Browse the repository at this point in the history
  • Loading branch information
@brentyi
brentyi committed Nov 27, 2023
1 parent 467bc58 commit c2505b9
Show file tree
Hide file tree
Showing 9 changed files with 520 additions and 86 deletions.
3 changes: 2 additions & 1 deletion src/viser/_client_autobuild.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ def ensure_client_is_built() -> None:
if _check_viser_yarn_running():
# Don't run `yarn build` if `yarn start` is already running.
rich.print(
"[bold](viser)[/bold] The Viser viewer looks like it has been launched via `yarn start`. Skipping build check..."
"[bold](viser)[/bold] The Viser viewer looks like it has been launched via"
" `yarn start`. Skipping build check..."
)
build = False
elif not (build_dir / "index.html").exists():
Expand Down
211 changes: 196 additions & 15 deletions src/viser/_gui_api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,15 @@ def gui_folder(self, label: str) -> GuiFolderHandle:
def add_gui_folder(
self, label: str, order: Optional[float] = None
) -> GuiFolderHandle:
"""Add a folder, and return a handle that can be used to populate it."""
"""Add a folder, and return a handle that can be used to populate it.
Args:
label: Label to display on the folder.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used as a context to populate the folder.
"""
folder_container_id = _make_unique_id()
order = _apply_default_order(order)
self._get_api()._queue(
Expand All @@ -208,7 +216,15 @@ def add_gui_modal(
order: Optional[float] = None,
) -> GuiModalHandle:
"""Show a modal window, which can be useful for popups and messages, then return
a handle that can be used to populate it."""
a handle that can be used to populate it.
Args:
title: Title to display on the modal.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used as a context to populate the modal.
"""
modal_container_id = _make_unique_id()
order = _apply_default_order(order)
self._get_api()._queue(
Expand All @@ -227,7 +243,14 @@ def add_gui_tab_group(
self,
order: Optional[float] = None,
) -> GuiTabGroupHandle:
"""Add a tab group."""
"""Add a tab group.
Args:
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used as a context to populate the tab group.
"""
tab_group_id = _make_unique_id()
order = _apply_default_order(order)
return GuiTabGroupHandle(
Expand All @@ -246,7 +269,16 @@ def add_gui_markdown(
image_root: Optional[Path] = None,
order: Optional[float] = None,
) -> GuiMarkdownHandle:
"""Add markdown to the GUI."""
"""Add markdown to the GUI.
Args:
content: Markdown content to display.
image_root: Optional root directory to resolve relative image paths.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
handle = GuiMarkdownHandle(
_gui_api=self,
_id=_make_unique_id(),
Expand Down Expand Up @@ -289,7 +321,20 @@ def add_gui_button(
order: Optional[float] = None,
) -> GuiButtonHandle:
"""Add a button to the GUI. The value of this input is set to `True` every time
it is clicked; to detect clicks, we can manually set it back to `False`."""
it is clicked; to detect clicks, we can manually set it back to `False`.
Args:
label: Label to display on the button.
visible: Whether the button is visible.
disabled: Whether the button is disabled.
hint: Optional hint to display on hover.
color: Optional color to use for the button.
icon: Optional icon to display on the button.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""

# Re-wrap the GUI handle with a button interface.
id = _make_unique_id()
Expand Down Expand Up @@ -351,7 +396,19 @@ def add_gui_button_group(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiButtonGroupHandle[Any]: # Return types are specified in overloads.
"""Add a button group to the GUI."""
"""Add a button group to the GUI.
Args:
label: Label to display on the button group.
options: Sequence of options to display as buttons.
visible: Whether the button group is visible.
disabled: Whether the button group is disabled.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
initial_value = options[0]
id = _make_unique_id()
order = _apply_default_order(order)
Expand Down Expand Up @@ -381,7 +438,19 @@ def add_gui_checkbox(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[bool]:
"""Add a checkbox to the GUI."""
"""Add a checkbox to the GUI.
Args:
label: Label to display on the checkbox.
initial_value: Initial value of the checkbox.
disabled: Whether the checkbox is disabled.
visible: Whether the checkbox is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
assert isinstance(initial_value, bool)
id = _make_unique_id()
order = _apply_default_order(order)
Expand All @@ -408,7 +477,19 @@ def add_gui_text(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[str]:
"""Add a text input to the GUI."""
"""Add a text input to the GUI.
Args:
label: Label to display on the text input.
initial_value: Initial value of the text input.
disabled: Whether the text input is disabled.
visible: Whether the text input is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
assert isinstance(initial_value, str)
id = _make_unique_id()
order = _apply_default_order(order)
Expand Down Expand Up @@ -438,7 +519,24 @@ def add_gui_number(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[IntOrFloat]:
"""Add a number input to the GUI, with user-specifiable bound and precision parameters."""
"""Add a number input to the GUI, with user-specifiable bound and precision parameters.
Args:
label: Label to display on the number input.
initial_value: Initial value of the number input.
min: Optional minimum value of the number input.
max: Optional maximum value of the number input.
step: Optional step size of the number input. Computed automatically if not
specified.
disabled: Whether the number input is disabled.
visible: Whether the number input is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""

assert isinstance(initial_value, (int, float))

if step is None:
Expand Down Expand Up @@ -489,7 +587,22 @@ def add_gui_vector2(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[Tuple[float, float]]:
"""Add a length-2 vector input to the GUI."""
"""Add a length-2 vector input to the GUI.
Args:
label: Label to display on the vector input.
initial_value: Initial value of the vector input.
min: Optional minimum value of the vector input.
max: Optional maximum value of the vector input.
step: Optional step size of the vector input. Computed automatically if not
disabled: Whether the vector input is disabled.
visible: Whether the vector input is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
initial_value = cast_vector(initial_value, 2)
min = cast_vector(min, 2) if min is not None else None
max = cast_vector(max, 2) if max is not None else None
Expand Down Expand Up @@ -535,7 +648,22 @@ def add_gui_vector3(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[Tuple[float, float, float]]:
"""Add a length-3 vector input to the GUI."""
"""Add a length-3 vector input to the GUI.
Args:
label: Label to display on the vector input.
initial_value: Initial value of the vector input.
min: Optional minimum value of the vector input.
max: Optional maximum value of the vector input.
step: Optional step size of the vector input. Computed automatically if not
disabled: Whether the vector input is disabled.
visible: Whether the vector input is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
initial_value = cast_vector(initial_value, 2)
min = cast_vector(min, 3) if min is not None else None
max = cast_vector(max, 3) if max is not None else None
Expand Down Expand Up @@ -606,7 +734,20 @@ def add_gui_dropdown(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiDropdownHandle[Any]: # Output type is specified in overloads.
"""Add a dropdown to the GUI."""
"""Add a dropdown to the GUI.
Args:
label: Label to display on the dropdown.
options: Sequence of options to display in the dropdown.
initial_value: Initial value of the dropdown.
disabled: Whether the dropdown is disabled.
visible: Whether the dropdown is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
if initial_value is None:
initial_value = options[0]
id = _make_unique_id()
Expand Down Expand Up @@ -641,7 +782,22 @@ def add_gui_slider(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[IntOrFloat]:
"""Add a slider to the GUI. Types of the min, max, step, and initial value should match."""
"""Add a slider to the GUI. Types of the min, max, step, and initial value should match.
Args:
label: Label to display on the slider.
min: Minimum value of the slider.
max: Maximum value of the slider.
step: Step size of the slider.
initial_value: Initial value of the slider.
disabled: Whether the slider is disabled.
visible: Whether the slider is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
assert max >= min
if step > max - min:
step = max - min
Expand Down Expand Up @@ -689,7 +845,20 @@ def add_gui_rgb(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[Tuple[int, int, int]]:
"""Add an RGB picker to the GUI."""
"""Add an RGB picker to the GUI.
Args:
label: Label to display on the RGB picker.
initial_value: Initial value of the RGB picker.
disabled: Whether the RGB picker is disabled.
visible: Whether the RGB picker is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""

id = _make_unique_id()
order = _apply_default_order(order)
return self._create_gui_input(
Expand All @@ -715,7 +884,19 @@ def add_gui_rgba(
hint: Optional[str] = None,
order: Optional[float] = None,
) -> GuiInputHandle[Tuple[int, int, int, int]]:
"""Add an RGBA picker to the GUI."""
"""Add an RGBA picker to the GUI.
Args:
label: Label to display on the RGBA picker.
initial_value: Initial value of the RGBA picker.
disabled: Whether the RGBA picker is disabled.
visible: Whether the RGBA picker is visible.
hint: Optional hint to display on hover.
order: Optional ordering, smallest values will be displayed first.
Returns:
A handle that can be used to interact with the GUI element.
"""
id = _make_unique_id()
order = _apply_default_order(order)
return self._create_gui_input(
Expand Down
7 changes: 5 additions & 2 deletions src/viser/_gui_handles.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -506,7 +506,8 @@ def remove(self) -> None:
def _get_data_url(url: str, image_root: Optional[Path]) -> str:
if not url.startswith("http") and not image_root:
warnings.warn(
"No `image_root` provided. All relative paths will be scoped to viser's installation path.",
"No `image_root` provided. All relative paths will be scoped to viser's"
" installation path.",
stacklevel=2,
)
if url.startswith("http"):
Expand All @@ -529,7 +530,9 @@ def _get_data_url(url: str, image_root: Optional[Path]) -> str:
def _parse_markdown(markdown: str, image_root: Optional[Path]) -> str:
markdown = re.sub(
r"\!\[([^]]*)\]\(([^]]*)\)",
lambda match: f"![{match.group(1)}]({_get_data_url(match.group(2), image_root)})",
lambda match: (
f"![{match.group(1)}]({_get_data_url(match.group(2), image_root)})"
),
markdown,
)
return markdown
Expand Down
Loading

0 comments on commit c2505b9

Please sign in to comment.