Add docstrings/API reference for UI subpackage (#42)

Author: cpsievert

.gitignore

@@ -104,3 +104,4 @@ ENV/
 typings/
 
 docs/source/generated/
+docs/source/reference/

docs/source/api.md

@@ -0,0 +1,232 @@
+Shiny for Python API Reference
+================
+
+* :ref:`search`
+
+
+Page containers
+~~~~~~~~~~~~~~~
+
+Create a user interface page container.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.page_navbar
+    ~shiny.ui.page_fluid
+    ~shiny.ui.page_fixed
+    ~shiny.ui.page_bootstrap
+
+
+UI Layout
+~~~~~~~~~
+
+Control the layout of multiple UI components.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.layout_sidebar
+    ~shiny.ui.panel_sidebar
+    ~shiny.ui.panel_main
+    ~shiny.ui.column
+    ~shiny.ui.row
+
+UI Inputs
+~~~~~~~~~
+
+Create UI that prompts the user for input values or interaction.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.input_select
+    ~shiny.ui.input_selectize
+    ~shiny.ui.input_slider
+    ~shiny.ui.input_date
+    ~shiny.ui.input_date_range
+    ~shiny.ui.input_checkbox
+    ~shiny.ui.input_checkbox_group
+    ~shiny.ui.input_radio_buttons
+    ~shiny.ui.input_numeric
+    ~shiny.ui.input_text
+    ~shiny.ui.input_text_area
+    ~shiny.ui.input_password
+    ~shiny.ui.input_action_button
+
+
+Update inputs
+~~~~~~~~~~~~~
+
+Programmatically update input values
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.update_select
+    ~shiny.ui.update_slider
+    ~shiny.ui.update_date
+    ~shiny.ui.update_date_range
+    ~shiny.ui.update_checkbox
+    ~shiny.ui.update_checkbox_group
+    ~shiny.ui.update_radio_buttons
+    ~shiny.ui.update_numeric
+    ~shiny.ui.update_text
+    ~shiny.ui.update_text_area
+    ~shiny.ui.update_navs
+
+
+Navigation (tab) panels
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Create segments of UI content.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.nav
+    ~shiny.ui.nav_item
+    ~shiny.ui.nav_spacer
+    ~shiny.ui.nav_menu
+    ~shiny.ui.navs_tab
+    ~shiny.ui.navs_tab_card
+    ~shiny.ui.navs_pill
+    ~shiny.ui.navs_pill_card
+    ~shiny.ui.navs_pill_list
+
+
+UI panels
+~~~~~~~~~
+
+Visually group together a section of UI components.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.panel_absolute
+    ~shiny.ui.panel_fixed
+    ~shiny.ui.panel_conditional
+    ~shiny.ui.panel_title
+    ~shiny.ui.panel_well
+
+
+Uploads & downloads
+~~~~~~~~~~~~~~~~~~~
+
+Allows users to upload and download files.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.input_file
+    ~shiny.ui.download_button
+
+
+Custom UI
+~~~~~~~~~~
+
+Lower-level UI functions for creating custom HTML/CSS/JS.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.HTML
+    ~shiny.ui.tags
+    ~shiny.ui.TagList
+    ~shiny.ui.insert_ui
+    ~shiny.ui.remove_ui
+
+
+Rendering outputs
+~~~~~~~~~~~~~~~~~~
+
+UI (`output_*()`) and server (``render_*()``) functions for generating content server-side.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.output_plot
+    ~shiny.render_plot
+    ~shiny.ui.output_image
+    ~shiny.render_image
+    ~shiny.ui.output_text
+    ~shiny.ui.output_text_verbatim
+    ~shiny.render_text
+    ~shiny.ui.output_ui
+    ~shiny.render_ui
+
+
+Reactive programming
+~~~~~~~~~~~~~~~~~~
+
+Reactive programming facilities for Python.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.reactive.Calc
+    ~shiny.reactive.Effect
+    ~shiny.reactive.Value
+    ~shiny.reactive.isolate
+    ~shiny.reactive.invalidate_later
+    ~shiny.reactive.flush
+    ~shiny.event
+
+
+Create and run applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create, run, stop, and hook into the lifecycle of Shiny applications.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.App
+    ~shiny.run_app
+    ~shiny.Inputs
+    ~shiny.Outputs
+    ~shiny.Session
+
+Display messages
+~~~~~~~~~~~~~~~~
+
+Display messages to the user.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.ui.help_text
+    ~shiny.ui.notification_show
+    ~shiny.ui.notification_remove
+    ~shiny.ui.Progress
+    ~shiny.ui.modal
+    ~shiny.ui.modal_show
+    ~shiny.ui.modal_remove
+    ~shiny.ui.modal_button
+
+Error validation
+~~~~~~~~~~~~~~~~
+
+Control how errors are shown to the user.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.req
+    ~shiny.types.SilentException
+    ~shiny.types.SilentCancelOutputException
+    ~shiny.types.SafeException
+
+
+Modules
+~~~~~~~
+
+Control application complexity by namespacing UI and server code.
+
+.. autosummary::
+    :toctree: reference/
+
+    ~shiny.modules.Module
+    ~shiny.modules.ModuleInputs
+    ~shiny.modules.ModuleOutputs
+    ~shiny.modules.ModuleSession

docs/source/index.md

@@ -0,0 +1,39 @@
+import os
+from typing import Callable, Any, TypeVar
+
+ex_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "examples")
+
+FuncType = Callable[..., Any]
+F = TypeVar("F", bound=FuncType)
+
+
+def add_example() -> Callable[[F], F]:
+    def _(func: F) -> F:
+        fn_name = func.__name__
+        example_file = os.path.join(ex_dir, fn_name, "app.py")
+        if not os.path.exists(example_file):
+            raise ValueError(f"No example for {fn_name}")
+
+        with open(example_file) as f:
+            example = [" " * 8 + x for x in f.readlines()]
+            example = "".join(example)
+
+        if func.__doc__ is None:
+            func.__doc__ = ""
+
+        func.__doc__ += (
+            f"\n\n    Examples\n    --------\n\n    .. code-block:: python\n\n{example}"
+        )
+
+        return func
+
+    return _
+
+
+def doc_format(**kwargs: str) -> Callable[[F], F]:
+    def _(func: F) -> F:
+        if func.__doc__:
+            func.__doc__ = func.__doc__.format(**kwargs)
+        return func
+
+    return _

docs/source/index.rst

@@ -0,0 +1,27 @@
+from shiny import *
+
+app_ui = ui.page_fluid(
+    ui.output_text("compute"),
+    ui.input_action_button("button", "Compute"),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    @output()
+    @render_text()
+    def compute():
+        p = ui.Progress(min=1, max=15)
+        p.set(message="Calculation in progress", detail="This may take a while...")
+
+        import time
+
+        for i in range(1, 15):
+            p.set(i, message="Computing")
+            time.sleep(0.1)
+
+        p.close()
+
+        return "Done computing!"
+
+
+app = App(app_ui, server)

examples/inputs/rstudio-logo.png

@@ -0,0 +1,16 @@
+import os
+from shiny import *
+
+app_ui = ui.page_fluid(
+    ui.download_button("downloadData", "Download"),
+)
+
+# For more examples of different types of download handlers, see:
+# https://github.com/rstudio/prism/blob/68ffc27/examples/download/app.py#L90
+def server(input: Inputs, output: Outputs, session: Session):
+    @session.download()
+    def downloadData():
+        return os.path.join(os.path.dirname(__file__), "mtcars.csv")
+
+
+app = App(app_ui, server)