From 57bb419e96ea3832579266c50fb6a847872f2509 Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 13:50:24 -0800 Subject: [PATCH 01/17] input_ docs copyedits --- shiny/ui/_input_action_button.py | 2 +- shiny/ui/_input_check_radio.py | 10 +++++----- shiny/ui/_input_password.py | 2 +- shiny/ui/_input_select.py | 18 ++++++++++++------ shiny/ui/_input_slider.py | 4 ++-- shiny/ui/_input_text.py | 22 +++++++++++----------- 6 files changed, 32 insertions(+), 26 deletions(-) diff --git a/shiny/ui/_input_action_button.py b/shiny/ui/_input_action_button.py index a2af0bc0f..139f63b54 100644 --- a/shiny/ui/_input_action_button.py +++ b/shiny/ui/_input_action_button.py @@ -30,7 +30,7 @@ def input_action_button( icon An icon to appear inline with the button/link. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g., '400px', or '100%'. kwargs Attributes to be applied to the button. diff --git a/shiny/ui/_input_check_radio.py b/shiny/ui/_input_check_radio.py index d00566364..6c330f62e 100644 --- a/shiny/ui/_input_check_radio.py +++ b/shiny/ui/_input_check_radio.py @@ -91,7 +91,7 @@ def input_switch( ) -> Tag: """ Create a switch that can be used to specify logical values. Similar to - ~shiny.ui.input_checkbox, but implies to the user that the change will take effect + :func:`~shiny.ui.input_checkbox`, but implies to the user that the change will take effect immediately. Parameters @@ -193,9 +193,9 @@ def input_checkbox_group( selected The values that should be initially selected, if any. inline - If `True`, the result is displayed inline + If `True`, the result is displayed inline. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g. '400px', or '100%'. Returns ------- @@ -263,9 +263,9 @@ def input_radio_buttons( selected The values that should be initially selected, if any. inline - If ``True``, the result is displayed inline + If ``True``, the result is displayed inline. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g. '400px', or '100%'. Returns ------- diff --git a/shiny/ui/_input_password.py b/shiny/ui/_input_password.py index 7e3214ca6..fbdd49eaf 100644 --- a/shiny/ui/_input_password.py +++ b/shiny/ui/_input_password.py @@ -30,7 +30,7 @@ def input_password( value Initial value. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g., '400px', or '100%'. placeholder The placeholder of the input. diff --git a/shiny/ui/_input_select.py b/shiny/ui/_input_select.py index 98f22d2d8..17ff243f3 100644 --- a/shiny/ui/_input_select.py +++ b/shiny/ui/_input_select.py @@ -37,8 +37,10 @@ _topics = { "Server value": """ -A list of strings, usually of length 1, with the value of the selected items. When -``multiple=True`` and nothing is selected, this value will be ``None``. +If `multiple=False`, the server value is a string with the value of the selected item. +If `multiple=True`, the server value is a tuple containing the values of the +selected items. When ``multiple=True`` and nothing is selected, this value +will be ``None``. """ } @@ -84,8 +86,10 @@ def input_selectize( Notes ------ ::: {.callout-note title="Server value"} - A list of strings, usually of length 1, with the value of the selected items. When - ``multiple=True`` and nothing is selected, this value will be ``None``. + If `multiple=False`, the server value is a string with the value of the selected item. + If `multiple=True`, the server value is a tuple containing the values of the + selected items. When ``multiple=True`` and nothing is selected, this value + will be ``None``. ::: See Also @@ -153,8 +157,10 @@ def input_select( Notes ------ ::: {.callout-note title="Server value"} - A list of strings, usually of length 1, with the value of the selected items. When - ``multiple=True`` and nothing is selected, this value will be ``None``. + If `multiple=False`, the server value is a string with the value of the selected item. + If `multiple=True`, the server value is a tuple containing the values of the + selected items. When ``multiple=True`` and nothing is selected, this value + will be ``None``. ::: See Also diff --git a/shiny/ui/_input_slider.py b/shiny/ui/_input_slider.py index 32902817f..d41f1fec3 100644 --- a/shiny/ui/_input_slider.py +++ b/shiny/ui/_input_slider.py @@ -98,7 +98,7 @@ def input_slider( animate ``True`` to show simple animation controls with default settings; ``False`` not to; or a custom settings list, such as those created using - :class:`AnimationOptions()`. + :class:`~AnimationOptions()`. width The CSS width, e.g. '400px', or '100%' sep @@ -132,7 +132,7 @@ def input_slider( ------ ::: {.callout-note title="Server value"} A number, date, or date-time (depending on the class of value), or in the case of - slider range, a list of two numbers/dates/date-times. + slider range, a tuple of two numbers/dates/date-times. ::: See Also diff --git a/shiny/ui/_input_text.py b/shiny/ui/_input_text.py index 61a328271..78da52bcd 100644 --- a/shiny/ui/_input_text.py +++ b/shiny/ui/_input_text.py @@ -22,7 +22,7 @@ def input_text( spellcheck: Optional[Literal["true", "false"]] = None, ) -> Tag: """ - Create an input control for entry of text values + Create an input control for entry of text values. Parameters ---------- @@ -33,17 +33,17 @@ def input_text( value Initial value. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g., '400px', or '100%'. placeholder A hint as to what can be entered into the control. autocomplete - Whether to enable browser autocompletion of the text input (default is None). - If None, then it will use the browser's default behavior. Other possible values + Whether to enable browser autocompletion of the text input (default is ``None``). + If `None`, then it will use the browser's default behavior. Other possible values include "on", "off", "name", "username", and "email". See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete for more. spellcheck - Whether to enable browser spell checking of the text input (default is None). If + Whether to enable browser spell checking of the text input (default is ``None``). If None, then it will use the browser's default behavior. Returns @@ -108,16 +108,16 @@ def input_text_area( value Initial value. width - The CSS width, e.g. '400px', or '100%' + The CSS width, e.g., '400px', or '100%'. height - The CSS height, e.g. '400px', or '100%' + The CSS height, e.g., '400px', or '100%'. cols - Value of the visible character columns of the input, e.g. 80. This argument will + Value of the visible character columns of the input, e.g., 80. This argument will only take effect if there is not a CSS width rule defined for this element; such a rule could come from the width argument of this function or from a containing page layout such as :func:`~shiny.ui.page_fluid`. rows - The value of the visible character rows of the input, e.g. 6. If the height + The value of the visible character rows of the input, e.g., 6. If the height argument is specified, height will take precedence in the browser's rendering. placeholder A hint as to what can be entered into the control. @@ -131,11 +131,11 @@ def input_text_area( autocomplete Whether to enable browser autocompletion of the text input (default is "off"). If `None`, then it will use the browser's default behavior. Other possible - values include "on", "name", "username", and "email". See [Mozila's autocomplete + values include "on", "name", "username", and "email". See [Mozilla's autocomplete documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for more. spellcheck - Whether to enable browser spell checking of the text input (default is None). If + Whether to enable browser spell checking of the text input (default is ``None``). If None, then it will use the browser's default behavior. Returns From 3d31920a20bc123929565fae3382984ccedb4d31 Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 13:50:51 -0800 Subject: [PATCH 02/17] layout copyedits --- shiny/ui/_layout.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py index 57f422ec4..2d89eb157 100644 --- a/shiny/ui/_layout.py +++ b/shiny/ui/_layout.py @@ -33,8 +33,8 @@ def layout_column_wrap( """ A grid-like, column-first layout - Wraps a 1d sequence of UI elements into a 2d grid. The number of columns (and rows) - in the grid dependent on the column `width` as well as the size of the display. + Wraps a 1d sequence of UI elements into a 2d grid. The number of columns + (and rows) in the grid depends on the column width and the size of the display. Parameters ---------- @@ -51,7 +51,7 @@ def layout_column_wrap( manually, either via a `style` attribute or a CSS stylesheet. If missing, a value of `200px` will be used. fixed_width - When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`, + When `width` is greater than 1 or is a CSS length unit, e.g., `"200px"`, `fixed_width` indicates whether that `width` value represents the absolute size of each column (`fixed_width=TRUE`) or the minimum size of a column (`fixed_width=FALSE`). When `fixed_width=FALSE`, new columns are added to a row From fe5b830a42d9c8c87be2a17ebc05cc0c1ac8f46d Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 13:51:19 -0800 Subject: [PATCH 03/17] popover, sidebar, tooltip copyedits --- shiny/ui/_popover.py | 1 - shiny/ui/_sidebar.py | 4 ++-- shiny/ui/_tooltip.py | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/shiny/ui/_popover.py b/shiny/ui/_popover.py index da11aca5e..93c476759 100644 --- a/shiny/ui/_popover.py +++ b/shiny/ui/_popover.py @@ -112,7 +112,6 @@ def fa_gear_icon(title: str): See Also -------- * - * :func:`~shiny.ui.toggle_popover` * :func:`~shiny.ui.update_popover` * :func:`~shiny.ui.tooltip` """ diff --git a/shiny/ui/_sidebar.py b/shiny/ui/_sidebar.py index f5a7bd1b2..a31a303cd 100644 --- a/shiny/ui/_sidebar.py +++ b/shiny/ui/_sidebar.py @@ -205,7 +205,7 @@ def sidebar( the second value will be used for left and right. If three, then the first will be used for top, the second will be left and right, and the third will be bottom. If four, then the values will be interpreted as top, right, bottom, and - left respectively. + left, respectively. Returns ------- @@ -342,7 +342,7 @@ def layout_sidebar( the second value will be used for left and right. If three, then the first will be used for top, the second will be left and right, and the third will be bottom. If four, then the values will be interpreted as top, right, bottom, and - left respectively. + left, respectively. height Any valid CSS unit to use for the height. diff --git a/shiny/ui/_tooltip.py b/shiny/ui/_tooltip.py index 0fb54d5ed..85c3b7a76 100644 --- a/shiny/ui/_tooltip.py +++ b/shiny/ui/_tooltip.py @@ -19,7 +19,7 @@ def tooltip( **kwargs: TagAttrValue, ) -> Tag: """ - Add a tooltip to a UI element + Add a tooltip to a UI element. Display additional information when focusing (or hovering over) a UI element. @@ -35,7 +35,7 @@ def tooltip( Contents to the tooltip's body. Or tag attributes that are supplied to the resolved :class:`~htmltools.Tag` object. id - A character string. Required to re-actively respond to the visibility of the + A character string. Required to reactively respond to the visibility of the tooltip (via the `input[id]` value) and/or update the visibility/contents of the tooltip. placement From b05f6883c14dbd4276b3796d9e601261f5ab805b Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 13:51:30 -0800 Subject: [PATCH 04/17] page copyedits --- shiny/ui/_page.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/shiny/ui/_page.py b/shiny/ui/_page.py index 98eee94cd..3d4ab19bc 100644 --- a/shiny/ui/_page.py +++ b/shiny/ui/_page.py @@ -144,7 +144,7 @@ def page_navbar( If provided, will create an input value that holds the currently selected nav item. selected - Choose a particular nav item to select by default value (should match it's + Choose a particular nav item to select by default value (should match its ``value``). sidebar A :func:`~shiny.ui.sidebar` component to display on every page. @@ -261,7 +261,7 @@ def page_fillable( **kwargs: TagAttrValue, ) -> Tag: """ - Creates a fillable page + Create a fillable page. Parameters ---------- @@ -419,7 +419,7 @@ def page_bootstrap( will be used as the lang in the ```` tag, as in ````. The default, `None`, results in an empty string. kwargs - Attributes on the the `` tag. + Attributes on the `` tag. Returns ------- From f1818410659ce6adedce55159c279147fa3068c6 Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 14:20:59 -0800 Subject: [PATCH 05/17] remove trailing whitespace --- shiny/ui/_input_select.py | 12 ++++++------ shiny/ui/_layout.py | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/shiny/ui/_input_select.py b/shiny/ui/_input_select.py index 17ff243f3..945640096 100644 --- a/shiny/ui/_input_select.py +++ b/shiny/ui/_input_select.py @@ -38,8 +38,8 @@ _topics = { "Server value": """ If `multiple=False`, the server value is a string with the value of the selected item. -If `multiple=True`, the server value is a tuple containing the values of the -selected items. When ``multiple=True`` and nothing is selected, this value +If `multiple=True`, the server value is a tuple containing the values of the +selected items. When ``multiple=True`` and nothing is selected, this value will be ``None``. """ } @@ -87,8 +87,8 @@ def input_selectize( ------ ::: {.callout-note title="Server value"} If `multiple=False`, the server value is a string with the value of the selected item. - If `multiple=True`, the server value is a tuple containing the values of the - selected items. When ``multiple=True`` and nothing is selected, this value + If `multiple=True`, the server value is a tuple containing the values of the + selected items. When ``multiple=True`` and nothing is selected, this value will be ``None``. ::: @@ -158,8 +158,8 @@ def input_select( ------ ::: {.callout-note title="Server value"} If `multiple=False`, the server value is a string with the value of the selected item. - If `multiple=True`, the server value is a tuple containing the values of the - selected items. When ``multiple=True`` and nothing is selected, this value + If `multiple=True`, the server value is a tuple containing the values of the + selected items. When ``multiple=True`` and nothing is selected, this value will be ``None``. ::: diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py index 2d89eb157..abafb4672 100644 --- a/shiny/ui/_layout.py +++ b/shiny/ui/_layout.py @@ -33,7 +33,7 @@ def layout_column_wrap( """ A grid-like, column-first layout - Wraps a 1d sequence of UI elements into a 2d grid. The number of columns + Wraps a 1d sequence of UI elements into a 2d grid. The number of columns (and rows) in the grid depends on the column width and the size of the display. Parameters From c1a124f160ca9ef3d83b03090279383c4a787b03 Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 14:29:46 -0800 Subject: [PATCH 06/17] valuebox copyedits --- shiny/ui/_valuebox.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/shiny/ui/_valuebox.py b/shiny/ui/_valuebox.py index 1f7f77c69..e096da6cf 100644 --- a/shiny/ui/_valuebox.py +++ b/shiny/ui/_valuebox.py @@ -247,11 +247,11 @@ def value_box_theme( Parameters --------- name - The name of the theme, e.g. `"primary"`, `"danger"`, `"purple"`). `name` can - also be a bootstrap supported color: `"blue"`, `"purple"`, `"pink"`, `"red"`, + The name of the theme, e.g. `"primary"`, `"danger"`, `"purple"`. `name` can + also be a Bootstrap-supported color: `"blue"`, `"purple"`, `"pink"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"teal"`, and `"cyan"`. These colors can be used with `bg-NAME`, `text-NAME`, and `bg-gradient-NAME1-NAME2`. If a `name` - does not start with `text-` or `bg-`, it will be auto prefixed with `bg-`. + does not start with `text-` or `bg-`, it will be auto-prefixed with `bg-`. fg,bg The background and foreground colors for the theme. @@ -312,7 +312,7 @@ def value_box( Value box An opinionated (:func:`~shiny.ui.card`-powered) box, designed for - displaying a `value` and `title`. Optionally, a `showcase` can provide for context + displaying a `value` and `title`. Optionally, a `showcase` can provide context for what the `value` represents (for example, it could hold an icon, or even a :func:`~shiny.ui.output_plot`). @@ -331,8 +331,8 @@ def value_box( showcase_layout One of `"left center"` (default), `"top right"` or `"bottom"`. Alternatively, you can customize the showcase layout options with the - :func:`~shiny.ui.showcase_left_center`, :func:`~shiny.ui.showcase_top_right()`, - or :func:`~shiny.ui.showcase_bottom()` functions. Use the options functions when + :func:`~shiny.ui.showcase_left_center`, :func:`~shiny.ui.showcase_top_right`, + or :func:`~shiny.ui.showcase_bottom` functions. Use the options functions when you want to control the height or width of the showcase area. theme The name of a theme (e.g. `"primary"`, `"danger"`, `"purple"`, `"bg-green"`, From 1b41a632fa05c7294a57d9c24a861aa094ff7445 Mon Sep 17 00:00:00 2001 From: skaltman Date: Wed, 6 Dec 2023 15:59:52 -0800 Subject: [PATCH 07/17] fix class formatting --- shiny/ui/_input_slider.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/ui/_input_slider.py b/shiny/ui/_input_slider.py index d41f1fec3..eeb37b389 100644 --- a/shiny/ui/_input_slider.py +++ b/shiny/ui/_input_slider.py @@ -98,7 +98,7 @@ def input_slider( animate ``True`` to show simple animation controls with default settings; ``False`` not to; or a custom settings list, such as those created using - :class:`~AnimationOptions()`. + :class:`~AnimationOptions`. width The CSS width, e.g. '400px', or '100%' sep From ab9a70559d57813405b2a63f846bb15a3f7ae8ad Mon Sep 17 00:00:00 2001 From: skaltman Date: Thu, 7 Dec 2023 11:44:41 -0800 Subject: [PATCH 08/17] navs copyedits --- shiny/ui/_navs.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/shiny/ui/_navs.py b/shiny/ui/_navs.py index f57338d76..2e7d6e622 100644 --- a/shiny/ui/_navs.py +++ b/shiny/ui/_navs.py @@ -114,11 +114,11 @@ def nav( *args UI elements to display when the item is active. value - The value of the item. This is used to determine whether the item is active - (when an ``id`` is provided to the nav container), programmatically select the - item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the - ``selected`` argument of the navigation container (e.g., - :func:`~shiny.ui.navset_tab`). + The value of the item. Use this value to determine whether the item is active + (when an ``id`` is provided to the nav container) or to programmatically + select the item (e.g., :func:`~shiny.ui.update_navs`). You can also + provide the value to the ``selected`` argument of the navigation container + (e.g., :func:`~shiny.ui.navset_tab`). icon An icon to appear inline with the button/link. @@ -314,11 +314,11 @@ def nav_menu( of two or more hyphens (e.g., ``---``), in which case it will be rendered as a divider. value - The value of the item. This is used to determine whether the item is active - (when an ``id`` is provided to the nav container), programmatically select the - item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the - ``selected`` argument of the navigation container (e.g., - :func:`~shiny.ui.navset_tab`). + The value of the item. Use this value to determine whether the item is active + (when an ``id`` is provided to the nav container) or to programmatically + select the item (e.g., :func:`~shiny.ui.update_navs`). You can also + provide the value to the ``selected`` argument of the navigation container + (e.g., :func:`~shiny.ui.navset_tab`). icon An icon to appear inline with the button/link. align @@ -833,7 +833,7 @@ def navset_card_underline( placement: Literal["above", "below"] = "above", ) -> NavSetCard: """ - Render nav items active/focused navigation links are styled with an underline inside a card container. + Render nav items inside a card container. Active/focused navigation links are styled with an underline. Parameters ---------- From 6b2d896d4b1db7a6be1d05e75e0452e0981c620e Mon Sep 17 00:00:00 2001 From: skaltman Date: Thu, 7 Dec 2023 12:09:40 -0800 Subject: [PATCH 09/17] panels copyedits --- shiny/ui/_bootstrap.py | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/shiny/ui/_bootstrap.py b/shiny/ui/_bootstrap.py index be0d23084..150f69220 100644 --- a/shiny/ui/_bootstrap.py +++ b/shiny/ui/_bootstrap.py @@ -110,9 +110,9 @@ def column( def panel_well(*args: TagChild | TagAttrs, **kwargs: TagAttrValue) -> Tag: """ - Create a well panel + Create a well panel. - Creates a panel with a slightly inset border and grey background. Equivalent to + Creates a panel with a slightly inset border and gray background. Equivalent to Bootstrap's ``well`` CSS class. Parameters @@ -147,7 +147,7 @@ def panel_conditional( **kwargs: TagAttrValue, ) -> Tag: """ - Create a conditional panel + Create a conditional panel. Show UI elements only if a ``JavaScript`` condition is ``true``. @@ -170,12 +170,13 @@ def panel_conditional( ---- In the JS expression, you can refer to input and output JavaScript objects that contain the current values of input and output. For example, if you have an input - with an id of foo, then you can use input.foo to read its value. (Be sure not to - modify the input/output objects, as this may cause unpredictable behavior.) + with an ``id`` of ``foo``, then you can use ``input.foo`` to read its value. + (Be sure not to modify the input/output objects, as this may cause unpredictable + behavior.) You are not recommended to use special JavaScript characters such as a period . in - the input id's, but if you do use them anyway, for example, ``id = "foo.bar"``, you - will have to use ``input["foo.bar"]`` instead of ``input.foo.bar`` to read the input + the input id's, but if you do use them anyway, for example, `id = "foo.bar"`, you + will have to use `input["foo.bar"]` instead of ``input.foo.bar`` to read the input value. Tip @@ -297,11 +298,11 @@ def panel_absolute( """ Create a panel of absolutely positioned content. - Creates a ``
`` tag whose CSS position is set to absolute (or fixed if ``fixed = - True``). The way absolute positioning works in HTML is that absolute coordinates are - specified relative to its nearest parent element whose position is not set to static - (which is the default), and if no such parent is found, then relative to the page - borders. If you're not sure what that means, just keep in mind that you may get + Creates a `
` tag whose CSS position is set to absolute (or fixed if ``fixed = + True``). In HTML, absolute coordinates are specified relative to an element's + nearest parent element whose position is not set to static (the default). + If no such parent is found, the coordinates are relative to the page borders. + If you're not sure what that means, just keep in mind that you may get strange results if you use this function from inside of certain types of panels. Parameters @@ -309,16 +310,16 @@ def panel_absolute( args UI elements to include inside the panel. top - Distance between the top of the panel, and the top of the page or parent + Distance between the top of the panel and the top of the page or parent container. left - Distance between the left side of the panel, and the left of the page or parent + Distance between the left side of the panel and the left of the page or parent container. right - Distance between the right side of the panel, and the right of the page or + Distance between the right side of the panel and the right of the page or parent container. bottom - Distance between the bottom of the panel, and the bottom of the page or parent + Distance between the bottom of the panel and the bottom of the page or parent container. width Width of the panel. @@ -351,12 +352,12 @@ def panel_absolute( results. Like most other distance parameters in Shiny, the position and size parameters take - a number (interpreted as pixels) or a valid CSS size string, such as ``"100px"`` - (100 pixels) or ``"25%"``. + a number (interpreted as pixels) or a valid CSS size string, such as `"100px"` + (100 pixels) or `"25%"`. - For arcane HTML reasons, to have the panel fill the page or parent you should + For arcane HTML reasons, to have the panel fill the page or parent, specify 0 for ``top``, ``left``, ``right``, and ``bottom`` rather than the more - obvious ``width = "100%"`` and ``height = "100%"``. + obvious `width = "100%"` and `height = "100%"`. """ style = css( From b051a1e7e252a61fee5208c9b10ef8d1b3ef3e16 Mon Sep 17 00:00:00 2001 From: skaltman Date: Thu, 7 Dec 2023 14:17:20 -0800 Subject: [PATCH 10/17] uploads and downloads copyedits --- shiny/ui/_download_button.py | 2 +- shiny/ui/_input_file.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/shiny/ui/_download_button.py b/shiny/ui/_download_button.py index 42c5d61de..305a2898b 100644 --- a/shiny/ui/_download_button.py +++ b/shiny/ui/_download_button.py @@ -74,7 +74,7 @@ def download_link( **kwargs: TagAttrValue, ) -> Tag: """ - Create a download button + Create a download button. Parameters ---------- diff --git a/shiny/ui/_input_file.py b/shiny/ui/_input_file.py index 25b93f23f..b1e8caa86 100644 --- a/shiny/ui/_input_file.py +++ b/shiny/ui/_input_file.py @@ -65,12 +65,12 @@ def input_file( ::: {.callout-note title="Server value"} A list of dictionaries (one for each file upload) with the following keys: - * name: The filename provided by the web browser. This is *not* the path to read + * ``name``: The filename provided by the web browser. This is *not* the path to read to get at the actual data that was uploaded (see 'datapath'). - * size: The size of the uploaded data, in bytes. - * type: The MIME type reported by the browser (for example, 'text/plain'), or + * ``size``: The size of the uploaded data, in bytes. + * ``type``: The MIME type reported by the browser (for example, 'text/plain'), or empty string if the browser didn't know. - * datapath: The path to a temp file that contains the data that was uploaded. + * ``datapath``: The path to a temp file that contains the data that was uploaded. This file may be deleted if the user performs another upload operation. ::: From 682dae641c8ebc043cea9c0b8b1bb8c94429ce21 Mon Sep 17 00:00:00 2001 From: skaltman Date: Thu, 7 Dec 2023 14:48:51 -0800 Subject: [PATCH 11/17] proofread custom ui pages --- shiny/ui/_include_helpers.py | 21 +++++++++++---------- shiny/ui/_insert.py | 32 ++++++++++++++------------------ shiny/ui/fill/_fill.py | 4 ++-- 3 files changed, 27 insertions(+), 30 deletions(-) diff --git a/shiny/ui/_include_helpers.py b/shiny/ui/_include_helpers.py index 1739bfc40..ba92c9286 100644 --- a/shiny/ui/_include_helpers.py +++ b/shiny/ui/_include_helpers.py @@ -27,7 +27,7 @@ def include_js( **kwargs: TagAttrValue, ) -> Tag: """ - Include a JavaScript file + Include a JavaScript file. Parameters ---------- @@ -46,9 +46,9 @@ def include_js( if the app's source is located at ``/app/app.py``, then ``path`` should be somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying 'safe' files should be located under ``/app/css/``). And finally, ``"inline"`` - is the inline the CSS file contents within a :func:`~ui.tags.style` tag. + includes the CSS file contents within a :func:`~ui.tags.style` tag. **kwargs - Attributes which are passed on to `~ui.tags.script` + Attributes which are passed on to `~ui.tags.script`. Returns @@ -59,9 +59,10 @@ def include_js( Note ---- This places a :func:`~ui.tags.script` tag in the :func:`~ui.tags.body` of the - document. If instead, you want to place the tag in the :func:`~ui.tags.head` of the - document, you can wrap it in ``head_content`` (in this case, just make sure you're - aware that the DOM probably won't be ready when the script is executed). + document. If you want to place the tag in the :func:`~ui.tags.head` of the + document instead, you can wrap it in ``head_content`` (in this case, just + make sure you're aware that the DOM probably won't be ready when the script + is executed). ```{python} #| eval: false @@ -98,7 +99,7 @@ def include_css( path: Path | str, *, method: Literal["link", "link_files", "inline"] = "link" ) -> Tag: """ - Include a CSS file + Include a CSS file. Parameters ---------- @@ -107,8 +108,8 @@ def include_css( method One of the following: ``"link"``, ``"link_files"``, or ``"inline"``. ``"link"`` is the link to the CSS file via a :func:`~ui.tags.link` tag. This method is - generally preferrable to ``"inline"`` since it allows the browser to cache the - file. ``"link_files"`` is the same as ``"link"``, but also allow for the CSS + generally preferable to ``"inline"`` since it allows the browser to cache the + file. ``"link_files"`` is the same as ``"link"``, but also allows for the CSS file to request other files within ``path``'s immediate parent directory (e.g., ``@import()`` another file). Note that this isn't the default behavior because you should **be careful not to include files in the same directory as ``path`` @@ -117,7 +118,7 @@ def include_css( if the app's source is located at ``/app/app.py``, then ``path`` should be somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying 'safe' files should be located under ``/app/css/``). And finally, ``"inline"`` - is the inline the CSS file contents within a :func:`~ui.tags.style` tag. + includes the CSS file contents within a :func:`~ui.tags.style` tag. Returns diff --git a/shiny/ui/_insert.py b/shiny/ui/_insert.py index c802cd741..3178aecf5 100644 --- a/shiny/ui/_insert.py +++ b/shiny/ui/_insert.py @@ -18,35 +18,31 @@ def insert_ui( session: Optional[Session] = None, ) -> None: """ - Insert UI objects + Insert UI objects. Parameters ---------- ui The UI object you want to insert. This can be anything that you usually put - inside your apps's ui function. If you're inserting multiple elements in one + inside your app's UI function. If you're inserting multiple elements in one call, make sure to wrap them in either a :func:`~shiny.ui.TagList` or a :func:`~shiny.ui.tags.div` (the latter option has the advantage that you can give it an id to make it easier to reference or remove it later on). If you want - to insert raw html, use :func:`~shiny.ui.HTML`. + to insert raw HTML, use :func:`~shiny.ui.HTML`. selector A string that is accepted by jQuery's selector (i.e. the string ``s`` to be placed in a ``$(s)`` jQuery call) which determines the element(s) relative to which you want to insert your UI object. where - Where your UI object should go relative to the selector: - - - beforeBegin: Before the selector element itself - - afterBegin: Just inside the selector element, before its first child - - beforeEnd: Just inside the selector element, after its last child (default) - - afterEnd: After the selector element itself - - Adapted from - https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML. + Where your UI object should go relative to the selector: "beforeBegin": + before the selector element itself; "beforeEnd": just inside the selector + element, after its last child (default); "afterEnd": after the selector + element itself. Adapted from + [https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML). multiple - In case your selector matches more than one element, multiple determines whether - Shiny should insert the UI object relative to all matched elements or just - relative to the first matched element (default). + In case your selector matches more than one element, ``multiple`` + determines whether Shiny should insert the UI object relative to all + matched elements or just relative to the first matched element (default). immediate Whether the UI object should be immediately inserted or removed, or whether Shiny should wait until all outputs have been updated and all effects have been @@ -95,19 +91,19 @@ def remove_ui( session: Optional[Session] = None, ) -> None: """ - Remove UI objects + Remove UI objects. Parameters ---------- selector A string that is accepted by jQuery's selector (i.e. the string ``x`` to be - placed in a ``$(x)`` jQuery call) which determines the element(s) to remove. If + placed in a ``$(x)`` jQuery call), which determines the element(s) to remove. If you want to remove a Shiny input or output, note that many of these are wrapped in ``
``s, so you may need to use a somewhat complex selector — see the Examples below. (Alternatively, you could also wrap the inputs/outputs that you want to be able to remove easily in a ``
`` with an id.) multiple - In case your selector matches more than one element, multiple determines whether + In case your selector matches more than one element, `multiple` determines whether Shiny should insert the UI object relative to all matched elements or just relative to the first matched element (default). immediate diff --git a/shiny/ui/fill/_fill.py b/shiny/ui/fill/_fill.py index 87f58bd37..5ea1cd4cc 100644 --- a/shiny/ui/fill/_fill.py +++ b/shiny/ui/fill/_fill.py @@ -46,7 +46,7 @@ def as_fill_item( tag: TagT, ) -> TagT: """ - Coerce a tag to a fill item + Coerce a tag to a fill item. Filling layouts are built on the foundation of _fillable containers_ and _fill items_ (_fill carriers_ are both _fillable containers_ and _fill items_). This is @@ -81,7 +81,7 @@ def remove_all_fill( tag: TagT, ) -> TagT: """ - Remove any filling layouts from a tag + Remove any filling layouts from a tag. Filling layouts are built on the foundation of _fillable containers_ and _fill items_ (_fill carriers_ are both _fillable containers_ and _fill items_). This is From 4b07db9760223eb6f0cccb89d0156c212ca5eef4 Mon Sep 17 00:00:00 2001 From: skaltman Date: Thu, 7 Dec 2023 17:19:07 -0800 Subject: [PATCH 12/17] update pages copyedits --- shiny/ui/_input_update.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/ui/_input_update.py b/shiny/ui/_input_update.py index 22a185d9c..4cf1fb3d7 100644 --- a/shiny/ui/_input_update.py +++ b/shiny/ui/_input_update.py @@ -45,7 +45,7 @@ The syntax of these functions is similar to the functions that created the inputs in the first place. For example, :func:`~shiny.ui.input_numeric` and - :func:`~update_numeric` take a similar set of arguments. + :func:`~shiny.ui.update_numeric` take a similar set of arguments. Any arguments with ``None`` values will be ignored; they will not result in any changes to the input object on the client. From 76710ee35a39010c2d96d15a6cd491d0c6c91d65 Mon Sep 17 00:00:00 2001 From: skaltman Date: Fri, 8 Dec 2023 10:20:13 -0800 Subject: [PATCH 13/17] update layouts copyedits --- shiny/ui/_accordion.py | 18 +++++++++--------- shiny/ui/_input_update.py | 4 ++-- shiny/ui/_sidebar.py | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/shiny/ui/_accordion.py b/shiny/ui/_accordion.py index 1631d05fc..aa7d3e431 100644 --- a/shiny/ui/_accordion.py +++ b/shiny/ui/_accordion.py @@ -397,7 +397,7 @@ def update_accordion( session: Optional[Session] = None, ) -> None: """ - Dynamically set accordions panel state + Dynamically set accordions' states. Dynamically (i.e., programmatically) update/modify :func:`~shiny.ui.accordion`s in a Shiny app. These functions require an `id` to be provided to the :func:`~shiny.ui.accordion` and must also be @@ -408,11 +408,11 @@ def update_accordion( id A string that matches an existing :func:`~shiny.ui.accordion`'s `id`. show - either a string or list of strings (used to identify particular + Either a string or list of strings (used to identify particular :func:`~shiny.ui.accordion_panel`(s) by their `value`) or a `bool` to set the state of all panels. session - A shiny session object (the default should almost always be used). + A Shiny session object (the default should almost always be used). References ---------- @@ -442,7 +442,7 @@ def insert_accordion_panel( session: Optional[Session] = None, ) -> None: """ - Insert an :func:`~shiny.ui.accordion_panel` + Insert an :func:`~shiny.ui.accordion_panel`. Parameters ---------- @@ -457,7 +457,7 @@ def insert_accordion_panel( `"after"` will append after the last panel and `"before"` will prepend before the first panel. session - A shiny session object (the default should almost always be used). + A Shiny session object (the default should almost always be used). References ---------- @@ -495,7 +495,7 @@ def remove_accordion_panel( session: Optional[Session] = None, ) -> None: """ - Remove an :func:`~shiny.ui.accordion_panel` + Remove an :func:`~shiny.ui.accordion_panel`. Parameters ---------- @@ -504,7 +504,7 @@ def remove_accordion_panel( target The `value` of an existing panel to remove. session - A shiny session object (the default should almost always be used). + A Shiny session object (the default should almost always be used). References ---------- @@ -552,7 +552,7 @@ def update_accordion_panel( session: Optional[Session] = None, ) -> None: """ - Dynamically update accordions panel contents + Dynamically update accordion panel contents. Dynamically (i.e., programmatically) update/modify :func:`~shiny.ui.accordion` panels in a Shiny app. These functions require an `id` to be provided to the :func:`~shiny.ui.accordion` and must also be @@ -573,7 +573,7 @@ def update_accordion_panel( icon If not missing, the new icon of the panel. session - A shiny session object (the default should almost always be used). + A Shiny session object (the default should almost always be used). References ---------- diff --git a/shiny/ui/_input_update.py b/shiny/ui/_input_update.py index 4cf1fb3d7..9f378c5ff 100644 --- a/shiny/ui/_input_update.py +++ b/shiny/ui/_input_update.py @@ -909,7 +909,7 @@ def update_tooltip( session: Optional[Session] = None, ) -> None: """ - Update tooltip contents + Update tooltip contents. Parameters ---------- @@ -971,7 +971,7 @@ def update_popover( title The new title of the popover. show - Opens (`True`) or closes (`False) the popover. + Opens (`True`) or closes (`False`) the popover. session A Shiny session object (the default should almost always be used). diff --git a/shiny/ui/_sidebar.py b/shiny/ui/_sidebar.py index a31a303cd..3ea322cc7 100644 --- a/shiny/ui/_sidebar.py +++ b/shiny/ui/_sidebar.py @@ -504,7 +504,7 @@ def update_sidebar( session: Optional[Session] = None, ) -> None: """ - Update a sidebar's visibility + Update a sidebar's visibility. Set a :func:`~shiny.ui.sidebar` state during an active Shiny user session. From 48559429d90f65f183d4cff7eeb3409bc6b759bc Mon Sep 17 00:00:00 2001 From: skaltman Date: Fri, 8 Dec 2023 10:48:56 -0800 Subject: [PATCH 14/17] revert link formatting --- shiny/ui/_insert.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/ui/_insert.py b/shiny/ui/_insert.py index 3178aecf5..913068867 100644 --- a/shiny/ui/_insert.py +++ b/shiny/ui/_insert.py @@ -38,7 +38,7 @@ def insert_ui( before the selector element itself; "beforeEnd": just inside the selector element, after its last child (default); "afterEnd": after the selector element itself. Adapted from - [https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML). + https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML. multiple In case your selector matches more than one element, ``multiple`` determines whether Shiny should insert the UI object relative to all From 0d05212d36a23b612c6a97d7045908da7c5d9cf1 Mon Sep 17 00:00:00 2001 From: skaltman Date: Fri, 8 Dec 2023 15:25:19 -0800 Subject: [PATCH 15/17] outputs copyedits --- shiny/render/_dataframe.py | 2 +- shiny/render/_render.py | 17 ++++++++++------- shiny/render/transformer/_transformer.py | 4 ++-- shiny/ui/_output.py | 7 ++++--- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/shiny/render/_dataframe.py b/shiny/render/_dataframe.py index f788c0896..2e3af17ce 100644 --- a/shiny/render/_dataframe.py +++ b/shiny/render/_dataframe.py @@ -260,7 +260,7 @@ def data_frame( _fn: DataFrameTransformer.ValueFn | None = None, ) -> DataFrameTransformer.OutputRenderer | DataFrameTransformer.OutputRendererDecorator: """ - Reactively render a Pandas data frame object (or similar) as an interactive table or + Reactively render a pandas `DataFrame` object (or similar) as an interactive table or grid. Features fast virtualized scrolling, sorting, filtering, and row selection (single or multiple). diff --git a/shiny/render/_render.py b/shiny/render/_render.py index 80ce58a72..9c0d986e0 100644 --- a/shiny/render/_render.py +++ b/shiny/render/_render.py @@ -354,7 +354,7 @@ def image( Returns ------- : - A decorator for a function that returns an `~shiny.types.ImgData` object. + A decorator for a function that returns an :func:`~shiny.types.ImgData` object. Tip ---- @@ -457,12 +457,14 @@ def table( **kwargs: object, ) -> TableTransformer.OutputRenderer | TableTransformer.OutputRendererDecorator: """ - Reactively render a Pandas data frame object (or similar) as a basic HTML table. + Reactively render a pandas ``DataFrame`` object (or similar) as a basic HTML + table. - Consider using ~shiny.render.data_frame instead of this renderer, as it provides - high performance virtual scrolling, built-in filtering and sorting, and a better - default appearance. This renderer may still be helpful if you use pandas styling - features that are not currently supported by ~shiny.render.data_frame. + Consider using :func:`~shiny.render.data_frame` instead of this renderer, as + it provides high performance virtual scrolling, built-in filtering and sorting, + and a better default appearance. This renderer may still be helpful if you + use pandas styling features that are not currently supported by + :func:`~shiny.render.data_frame`. Parameters ---------- @@ -544,7 +546,8 @@ def ui( Returns ------- : - A decorator for a function that returns an object of type `~shiny.ui.TagChild`. + A decorator for a function that returns an object of type + :class:`~shiny.ui.TagChild`. Tip ---- diff --git a/shiny/render/transformer/_transformer.py b/shiny/render/transformer/_transformer.py index 5efbf2e53..0392f4d97 100644 --- a/shiny/render/transformer/_transformer.py +++ b/shiny/render/transformer/_transformer.py @@ -652,7 +652,7 @@ def output_transformer( * The first parameter to the handler function has the class :class:`~shiny.render.transformer.TransformerMetadata` and is typically called - `_meta`. This information gives context the to the handler while trying to + `_meta`. This information gives context to the handler while trying to resolve the app-supplied value function (typically called `_fn`). * The second parameter is the app-defined output value function (e.g. `_fn`). It's return type (`IT`) determines what types can be returned by the app-supplied @@ -666,7 +666,7 @@ def output_transformer( default value. No default value is needed for keyword arguments that are passed through (e.g. `**kwargs: Any`). - The tranform function's return type (`OT`) determines the output type of the + The transform function's return type (`OT`) determines the output type of the :class:`~shiny.render.transformer.OutputRenderer`. Note that in many cases (but not all!) `IT` and `OT` will be the same. The `None` type should typically be defined in both `IT` and `OT`. If `IT` allows for `None` values, it (typically) signals that diff --git a/shiny/ui/_output.py b/shiny/ui/_output.py index db780ca1b..9fff1b631 100644 --- a/shiny/ui/_output.py +++ b/shiny/ui/_output.py @@ -246,7 +246,7 @@ def output_text( id An output id. inline - If ``True``, the result is displayed inline + If ``True``, the result is displayed inline. container A Callable that returns the output container. @@ -284,7 +284,8 @@ def output_text_verbatim(id: str, placeholder: bool = False) -> Tag: An output id. placeholder If the output is empty or ``None``, should an empty rectangle be displayed to - serve as a placeholder? (does not affect behavior when the output is nonempty) + serve as a placeholder? (This does not affect behavior when the output + is nonempty.) Returns ------- @@ -345,7 +346,7 @@ def output_ui( id An output id. inline - If ``True``, the result is displayed inline + If ``True``, the result is displayed inline. container A Callable that returns the output container. fill From 8b9972f696e01111b314ea3ba8f636b182ff6319 Mon Sep 17 00:00:00 2001 From: skaltman Date: Fri, 8 Dec 2023 15:28:57 -0800 Subject: [PATCH 16/17] double backtick --- shiny/ui/_insert.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/shiny/ui/_insert.py b/shiny/ui/_insert.py index 913068867..788e03038 100644 --- a/shiny/ui/_insert.py +++ b/shiny/ui/_insert.py @@ -103,9 +103,9 @@ def remove_ui( Examples below. (Alternatively, you could also wrap the inputs/outputs that you want to be able to remove easily in a ``
`` with an id.) multiple - In case your selector matches more than one element, `multiple` determines whether - Shiny should insert the UI object relative to all matched elements or just - relative to the first matched element (default). + In case your selector matches more than one element, ``multiple`` determines + whether Shiny should insert the UI object relative to all matched elements + or just relative to the first matched element (default). immediate Whether the UI object should be immediately inserted or removed, or whether Shiny should wait until all outputs have been updated and all effects have been From 23bfd1f51e0d3122464c5f1b3180f2382baf2e74 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Mon, 18 Dec 2023 14:54:10 -0500 Subject: [PATCH 17/17] Remove white space --- shiny/ui/_insert.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/ui/_insert.py b/shiny/ui/_insert.py index 788e03038..13c4fbdd4 100644 --- a/shiny/ui/_insert.py +++ b/shiny/ui/_insert.py @@ -34,7 +34,7 @@ def insert_ui( placed in a ``$(s)`` jQuery call) which determines the element(s) relative to which you want to insert your UI object. where - Where your UI object should go relative to the selector: "beforeBegin": + Where your UI object should go relative to the selector: "beforeBegin": before the selector element itself; "beforeEnd": just inside the selector element, after its last child (default); "afterEnd": after the selector element itself. Adapted from