Function reference edits

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).
 

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
     ----

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

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
     ----------

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,28 +298,28 @@ def panel_absolute(
     """
     Create a panel of absolutely positioned content.
 
-    Creates a ``<div>`` 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 `<div>` 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
     ----------
     *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(

shiny/ui/_download_button.py

@@ -74,7 +74,7 @@ def download_link(
     **kwargs: TagAttrValue,
 ) -> Tag:
     """
-    Create a download button
+    Create a download button.
 
     Parameters
     ----------

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
     ----------

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
     -------

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.
     :::
 

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.
 

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