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/_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/_bootstrap.py b/shiny/ui/_bootstrap.py index 3c1c2cc42..d6e24b6f0 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( diff --git a/shiny/ui/_download_button.py b/shiny/ui/_download_button.py index c9d3a5195..be0e92fd4 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/_include_helpers.py b/shiny/ui/_include_helpers.py index 88c339bb5..8ceebb12f 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 ---------- @@ -51,7 +51,7 @@ def include_js( * ``"inline"`` is the inline 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 @@ -62,9 +62,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 @@ -101,7 +102,7 @@ def include_css( path: Path | str, *, method: Literal["link", "link_files", "inline"] = "link" ) -> Tag: """ - Include a CSS file + Include a CSS file. Parameters ---------- 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_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. ::: 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..945640096 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..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 @@ -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 diff --git a/shiny/ui/_input_update.py b/shiny/ui/_input_update.py index 3c02d7565..85571e40c 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. @@ -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/_insert.py b/shiny/ui/_insert.py index c802cd741..13c4fbdd4 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 + 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. 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,21 +91,21 @@ 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 - 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 diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py index 5223f8b04..c4bce6481 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 ---------- @@ -53,7 +53,7 @@ def layout_column_wrap( property 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`). diff --git a/shiny/ui/_navs.py b/shiny/ui/_navs.py index 7a16b2823..2f23351ab 100644 --- a/shiny/ui/_navs.py +++ b/shiny/ui/_navs.py @@ -114,11 +114,11 @@ def nav_panel( *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 ---------- diff --git a/shiny/ui/_output.py b/shiny/ui/_output.py index 213fc9b0b..7accac6a1 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 diff --git a/shiny/ui/_page.py b/shiny/ui/_page.py index d35949a16..207bd1ab0 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 ---------- 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 4f2af4e5d..28007af72 100644 --- a/shiny/ui/_sidebar.py +++ b/shiny/ui/_sidebar.py @@ -512,7 +512,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. 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 diff --git a/shiny/ui/_valuebox.py b/shiny/ui/_valuebox.py index ed9738768..219c77cbd 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"`, diff --git a/shiny/ui/fill/_fill.py b/shiny/ui/fill/_fill.py index 462300a23..6dd6d1c88 100644 --- a/shiny/ui/fill/_fill.py +++ b/shiny/ui/fill/_fill.py @@ -45,7 +45,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