docs: Function Reference Proofreads (#919)

Co-authored-by: Garrett Grolemund <[email protected]>
Co-authored-by: Garrett Grolemund <[email protected]>

Author: schloerke

docs/_renderer.py

@@ -16,6 +16,8 @@
 from quartodoc.pandoc.blocks import DefinitionList
 from quartodoc.renderers.base import convert_rst_link_to_md, sanitize
 
+# from quartodoc.ast import preview
+
 SHINY_PATH = Path(files("shiny").joinpath())
 
 SHINYLIVE_CODE_TEMPLATE = """
@@ -142,9 +144,37 @@ def render_annotation(self, el: exp.ExprName):
         return f"[{el.name}](`{el.canonical_path}`)"
 
     @dispatch
-    def summarize(self, el: dc.Object | dc.Alias):
-        result = super().summarize(el)
-        return html.escape(result)
+    # Overload of `quartodoc.renderers.md_renderer` to fix bug where the descriptions
+    # are cut off and never display other places. Fixing by always displaying the
+    # documentation.
+    def summarize(self, obj: Union[dc.Object, dc.Alias]) -> str:
+        # get high-level description
+        doc = obj.docstring
+        if doc is None:
+            docstring_parts = []
+        else:
+            docstring_parts = doc.parsed
+
+        if len(docstring_parts) and isinstance(
+            docstring_parts[0], ds.DocstringSectionText
+        ):
+            description = docstring_parts[0].value
+
+            # ## Approach: Always return the full description!
+            return description
+
+            # ## Alternative: Add ellipsis if the lines are cut off
+
+            # # If the description is more than one line, only show the first line.
+            # # Add `...` to indicate the description was truncated
+            # parts = description.split("\n")
+            # short = parts[0]
+            # if len(parts) > 1:
+            #     short += "…"
+
+            # return short
+
+        return ""
 
     # Consolidate the parameter type info into a single column
     @dispatch

shiny/_app.py

@@ -46,12 +46,12 @@ class App:
     ----------
     ui
         The UI definition for the app (e.g., a call to :func:`~shiny.ui.page_fluid` or
-        :func:`~shiny.ui.page_fixed`, with layouts and controls nested inside). You can
+        similar, with layouts and controls nested inside). You can
         also pass a function that takes a :class:`~starlette.requests.Request` and
         returns a UI definition, if you need the UI definition to be created dynamically
         for each pageview.
     server
-        A function which is called once for each session, ensuring that each app is
+        A function which is called once for each session, ensuring that each session is
         independent.
     static_assets
         Static files to be served by the app. If this is a string or Path object, it

shiny/_main.py

@@ -197,7 +197,7 @@ def run_app(
     **kwargs: object,
 ) -> None:
     """
-    Starts a Shiny app. Press ``Ctrl+C`` (or ``Ctrl+Break`` on Windows) to stop.
+    Starts a Shiny app. Press ``Ctrl+C`` (or ``Ctrl+Break`` on Windows) to stop the app.
 
     Parameters
     ----------
@@ -207,8 +207,8 @@ def run_app(
         directory. In other cases, the app location can be specified as a
         ``<module>:<attribute>`` string where the ``:<attribute>`` is only necessary if
         the application is named something other than ``app``. Note that ``<module>``
-        can be relative path to a ``.py`` file or a directory (with an ``app.py`` file
-        inside it); and in this case, the relative path is resolved relative to the
+        can be a relative path to a ``.py`` file or a directory (with an ``app.py`` file
+        inside of it); and in this case, the relative path is resolved relative to the
         ``app_dir`` directory.
     host
         The address that the app should listen on.
@@ -220,8 +220,8 @@ def run_app(
     reload
         Enable auto-reload.
     reload_dirs
-        List of directories (in addition to the app directory) to watch for changes that
-        will trigger app reloading.
+        A list of directories (in addition to the app directory) to watch for changes that
+        will trigger an app reload.
     reload_includes
         List or tuple of file globs to indicate which files should be monitored for
         changes. Can be combined with `reload_excludes`.
@@ -233,7 +233,7 @@ def run_app(
     log_level
         Log level.
     app_dir
-        Look for ``app`` under this directory (by adding this to the ``PYTHONPATH``).
+        The directory to look for ``app`` under (by adding this to the ``PYTHONPATH``).
     factory
         Treat ``app`` as an application factory, i.e. a () -> <ASGI app> callable.
     launch_browser
@@ -245,7 +245,7 @@ def run_app(
     Tip
     ---
     The ``shiny run`` command-line interface (which comes installed with Shiny) provides
-    the same functionality as this function.
+    the same functionality as :func:`~shiny.run_app`.
 
     Examples
     --------

shiny/_validation.py

@@ -26,6 +26,13 @@ def req(*args: T, cancel_output: bool = False) -> T | None:
     This is a convenient shorthand for throwing :func:`~shiny.types.SilentException` /
     :func:`~shiny.types.SilentCancelOutputException` if any of the arguments are falsy.
 
+    The term "falsy" generally indicates that a value is considered `False` when
+    encountered in a logical context. We use the term a little loosely here; our usage
+    tries to match the intuitive notions of "Is this value missing or available?", or
+    "Has the user provided an answer?", or in the case of action buttons, "Has the
+    button been clicked?". So `False`, `None`, `0`, and `""` would be examples of Falsy
+    values.
+
     Parameters
     ----------
     *args

shiny/experimental/ui/_card.py

@@ -48,30 +48,30 @@ def card(
     """
     A Bootstrap card component
 
-    A general purpose container for grouping related UI elements together with a border
-    and optional padding. To learn more about `card()`s, see [this
+    A card is a general purpose container that groups related UI elements together with a border
+    and optional padding. To learn more about `card()`s, see [the bslib card
     article](https://rstudio.github.io/bslib/articles/cards.html).
 
     Parameters
     ----------
     *args
-        Unnamed arguments can be any valid child of an :class:`~htmltools.Tag` (which
-        includes card items such as :func:`~shiny.experimental.ui.card_body`.
+        Unnamed arguments can be any valid child of an :class:`~htmltools.Tag` (This
+        includes card items such as :func:`~shiny.experimental.ui.card_body`).
     full_screen
-        If `True`, an icon will appear when hovering over the card body. Clicking the
+        If `True`, an icon will appear when the user's pointer hovers over the card body. Clicking the
         icon expands the card to fit viewport size.
-    height,max_height,min_height
-        Any valid CSS unit (e.g., `height="200px"`). Doesn't apply when a card is made
-        `full_screen` (in this case, consider setting a `height` in
-        :func:`~shiny.experimental.ui.card_body`).
+    height, max_height, min_height
+        Any valid CSS unit (e.g., `height="200px"`). These will not apply when a card is made
+        `full_screen`. In this case, consider setting a `height` in
+        :func:`~shiny.experimental.ui.card_body`.
     fill
         Whether or not to allow the card to grow/shrink to fit a fillable container with
         an opinionated height (e.g., :func:`~shiny.ui.page_fillable`).
     class_
         Additional CSS classes for the returned Tag.
     wrapper
-        A function (which returns a UI element) to call on unnamed arguments in `*args`
-        which are not already card item(s) (like
+        A function that returns a UI element to call on any unnamed arguments in `*args`
+        that are not already card item(s) (like
         :func:`~shiny.ui.card_header`,
         :func:`~shiny.experimental.ui.card_body`, etc.). Note that non-card items are
         grouped together into one `wrapper` call (e.g. given `card("a", "b",
@@ -83,17 +83,17 @@ def card(
     Returns
     -------
     :
-        An :func:`~shiny.ui.tags.div` tag.
+        A :func:`~shiny.ui.tags.div` tag.
 
     See Also
     --------
     * :func:`~shiny.ui.layout_column_wrap` for laying out multiple cards
-      (or multiple columns inside a card).
-    * :func:`~shiny.ui.card_header` for creating a header within the card.
-    * :func:`~shiny.experimental.ui.card_title` for creating a title within the card body.
-    * :func:`~shiny.experimental.ui.card_body` for putting content inside the card.
-    * :func:`~shiny.ui.card_footer` for creating a footer within the card.
-    * :func:`~shiny.experimental.ui.card_image` for adding an image to the card.
+      or multiple columns inside a card.
+    * :func:`~shiny.ui.card_header` for creating a header within a card.
+    * :func:`~shiny.experimental.ui.card_title` for creating a title within a card body.
+    * :func:`~shiny.experimental.ui.card_body` for putting content inside a card.
+    * :func:`~shiny.ui.card_footer` for creating a footer within a card.
+    * :func:`~shiny.experimental.ui.card_image` for adding an image to a card.
     """
     return _card_impl(
         *args,
@@ -118,33 +118,35 @@ def card_title(
     **kwargs: TagAttrValue,
 ) -> Tagifiable:
     """
-    Card title container
+    A card title container
 
-    A general container for the "title" of a :func:`~shiny.ui.card`. This component is designed
+    :func:`~shiny.experimental.ui.card_title` creates a general container for the "title" of
+    a :func:`~shiny.ui.card`. This component is designed
     to be provided as a direct child to :func:`~shiny.ui.card`.
 
     Parameters
     ----------
     *args
-        Contents to the card's title. Or tag attributes that are supplied to the
+        Contents to appear in the card's title, or tag attributes to pass to the
         resolved :class:`~htmltools.Tag` object.
     container
-        Method for the returned Tag object. Defaults to :func:`shiny.ui.tags.h5`.
+        Method for the returned :class:`~htmltools.Tag` object. Defaults to
+        :func:`~shiny.ui.tags`.h5.
     **kwargs
-        Additional HTML attributes for the returned Tag.
+        Additional HTML attributes for the returned :class:`~htmltools.Tag` object.
 
     Returns
     -------
     :
-        A Tag object.
+        An :class:`~htmltools.Tag` object.
 
     See Also
     --------
     * :func:`~shiny.ui.card` for creating a card component.
-    * :func:`~shiny.ui.card_header` for creating a header within the card.
-    * :func:`~shiny.experimental.ui.card_body` for putting content inside the card.
-    * :func:`~shiny.ui.card_footer` for creating a footer within the card.
-    * :func:`~shiny.experimental.ui.card_image` for adding an image to the card.
+    * :func:`~shiny.ui.card_header` for creating a header within a card.
+    * :func:`~shiny.experimental.ui.card_body` for putting content inside a card.
+    * :func:`~shiny.ui.card_footer` for creating a footer within a card.
+    * :func:`~shiny.experimental.ui.card_image` for adding an image to a card.
     """
     return container(*args, **kwargs)
 
@@ -188,21 +190,22 @@ def card_image(
     **kwargs: TagAttrValue,
 ) -> Tagifiable:
     """
-    Card image container
+    A card image container
 
-    A general container for an image within a :func:`~shiny.ui.card`. This component is designed to be
+    :func:`~shiny.experimental.ui.card_image` creates a general container for an image within a
+    :func:`~shiny.ui.card`. This component is designed to be
     provided as a direct child to :func:`~shiny.ui.card`.
 
     Parameters
     ----------
     file
-        A file path pointing an image. The image will be base64 encoded and provided to
-        the `src` attribute of the `<img>`. Alternatively, you may set this value to
+        A file path pointing to an image. The image will be base64 encoded and provided to
+        the `src` attribute of the `<img>` tag. Alternatively, you may set this value to
         `None` and provide the `src` yourself via `*args:TagAttrs` or
-        `**kwargs:TagAttrValue` (e.g. `{"src": "HOSTED_PATH_TO_IMAGE"}` or
+        `**kwargs:TagAttrValue` (e.g., `{"src": "HOSTED_PATH_TO_IMAGE"}` or
         `src="HOSTED_PATH_TO_IMAGE"`).
     *args
-        Dictionary of tag attributes that are supplied to the resolved
+        A dictionary of tag attributes that are supplied to the resolved
         :class:`~htmltools.Tag` object.
     href
         An optional URL to link to.
@@ -211,23 +214,24 @@ def card_image(
     mime_type
         The mime type of the `file`.
     class_
-        Additional CSS classes for the resolved Tag.
+        Additional CSS classes for the resolved :class:`~htmltools.Tag` object.
     height
-        Any valid CSS unit (e.g., `height="200px"`). Doesn't apply when a card is made
-        `full_screen` (in this case, consider setting a `height` in
-        :func:`~shiny.experimental.ui.card_body`).
+        Any valid CSS unit (e.g., `height="200px"`). `height` will not apply when a card is made
+        `full_screen`. In this case, consider setting a `height` in
+        :func:`~shiny.experimental.ui.card_body`.
     fill
         Whether to allow this element to grow/shrink to fit its `card` container.
     width
         Any valid CSS unit (e.g., `width="100%"`).
     container
-        Method to wrap the returned Tag object. Defaults to :func:`~shiny.experimental.ui.card_body`.
+        Method to wrap the returned :class:`~htmltools.Tag` object. Defaults to
+        :func:`~shiny.experimental.ui.card_body`.
         If :func:`~shiny.experimental.ui.card_body` is used, each image will be in separate cards. If
         the `container` method does not return a :class:`~shiny.ui.CardItem`, it
         allows for consecutive non-`CardItem` objects to be bundled into a single
         :func:`~shiny.experimental.ui.card_body` within :func:`~shiny.ui.card`.
     **kwargs
-        Additional HTML attributes for the resolved Tag.
+        Additional HTML attributes for the resolved :class:`~htmltools.Tag`.
     """
     src = None
     if file is not None: