Merge pull request #340 from rstudio/add-example-files

Author: wch

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Bug fixes
 
+* Closed #240, #330: Fixed live examples with additional files. (#340)
+
 ### Other changes
 
 

docs/source/index.rst

@@ -205,6 +205,8 @@ UI (`output_*()`) and server (``render``)ing functions for generating content se
     render.plot
     ui.output_image
     render.image
+    ui.output_table
+    render.table
     ui.output_text
     ui.output_text_verbatim
     render.text

docs/sphinxext/pyshinyapp.py

@@ -17,8 +17,11 @@
         :height: 500px
 """
 
+import base64
+import json
 import os
 import shutil
+import sys
 from os.path import abspath, dirname, join
 
 from docutils.nodes import Element, SkipNode
@@ -27,6 +30,18 @@
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
 
+if sys.version_info >= (3, 8):
+    from typing import Literal, TypedDict
+else:
+    from typing_extensions import Literal, TypedDict
+
+# This is the same as the FileContentJson type in TypeScript.
+class FileContentJson(TypedDict):
+    name: str
+    content: str
+    type: Literal["text", "binary"]
+
+
 # Local path to the shinylive/ directory (currently provided by rstudio/shinylive)
 # This is only needed for the "self-contained" version of the API reference.
 # (in other words, you can set this to "" if you already have the shinylive/ directory
@@ -46,10 +61,19 @@ def html(self):
             # TODO: allow the layout to be specified (right now I don't think we need
             # horizontal layout, but maybe someday we will)
             code = (
-                "#| standalone: true\n#| components: [editor, viewer]\n#| layout: vertical\n#| viewerHeight: 400\n"
+                "#| standalone: true\n#| components: [editor, viewer]\n#| layout: vertical\n#| viewerHeight: 400\n## file: app.py\n"
                 + code
             )
 
+            for f in self["files"]:
+                file_info = _read_file(f)
+                if file_info["type"] == "text":
+                    code += (
+                        f"\n\n## file: {os.path.basename(f)}\n{file_info['content']}"
+                    )
+                else:
+                    code += f"\n\n## file: {os.path.basename(f)}\n## type: binary\n{file_info['content']}"
+
         return (
             f'<pre class="shinylive-python" style="{style}"><code>{code}</code></pre>'
         )
@@ -59,8 +83,9 @@ def _run(self: SphinxDirective, type: str):
     code = "\n".join(self.content)
     width = self.options.pop("width", "100%")
     height = self.options.pop("height", None)
+    files = json.loads(self.options.pop("files", "[]"))
 
-    return [ShinyElement(type=type, code=code, height=height, width=width)]
+    return [ShinyElement(type=type, code=code, height=height, width=width, files=files)]
 
 
 class BaseDirective(SphinxDirective):
@@ -69,6 +94,7 @@ class BaseDirective(SphinxDirective):
     option_spec = {
         "width": directives.unchanged,
         "height": directives.unchanged,
+        "files": directives.unchanged,
     }
 
 
@@ -134,3 +160,23 @@ def skip(self: Sphinx, node: Element):
     app.add_directive("terminal", TerminalDirective)
 
     return {"version": "0.1"}
+
+
+def _read_file(filename: str) -> FileContentJson:
+    type: Literal["text", "binary"] = "text"
+    try:
+        with open(filename, "r") as f:
+            file_content = f.read()
+            type = "text"
+    except UnicodeDecodeError:
+        # If text failed, try binary.
+        with open(filename, "rb") as f:
+            file_content_bin = f.read()
+            file_content = base64.b64encode(file_content_bin).decode("utf-8")
+            type = "binary"
+
+    return {
+        "name": filename,
+        "content": file_content,
+        "type": type,
+    }

shiny/_docstring.py

@@ -1,3 +1,4 @@
+import json
 import os
 import sys
 from typing import Any, Callable, List, TypeVar
@@ -29,7 +30,7 @@ def add_example(
         "cell::",
         "terminal::",
     ] = "shinylive-editor::",
-    **options: str,
+    **options: object,
 ) -> Callable[[F], F]:
     """
     Add an example to the docstring of a function, method, or class.
@@ -61,10 +62,20 @@ def _(func: F) -> F:
             return func
 
         fn_name = func.__name__
-        example_file = os.path.join(ex_dir, fn_name, "app.py")
+        example_dir = os.path.join(ex_dir, fn_name)
+        example_file = os.path.join(example_dir, "app.py")
         if not os.path.exists(example_file):
             raise ValueError(f"No example for {fn_name}")
 
+        other_files: List[str] = []
+        for f in os.listdir(example_dir):
+            abs_f = os.path.join(example_dir, f)
+            if os.path.isfile(abs_f) and f != "app.py":
+                other_files.append(abs_f)
+
+        if "files" not in options:
+            options["files"] = json.dumps(other_files)
+
         if func.__doc__ is None:
             func.__doc__ = ""
 
@@ -97,7 +108,7 @@ def _(func: F) -> F:
                 "",
                 *example_prefix,
                 f".. {directive}",
-                *[f"{indent}:{k}: {v}" for k, v in options.items()],
+                *[f"    :{k}: {v}" for k, v in options.items()],
                 "",
                 example,
             ]

shiny/examples/file_reader/requirements.txt

@@ -0,0 +1,3 @@
+# Pandas needs Jinja2 for table styling, but it doesn't (yet) load automatically
+# in Pyodide, so we need to explicitly list it here.
+Jinja2

shiny/examples/output_table/requirements.txt

@@ -0,0 +1,3 @@
+# Pandas needs Jinja2 for table styling, but it doesn't (yet) load automatically
+# in Pyodide, so we need to explicitly list it here.
+Jinja2

shiny/ui/_output.py

@@ -153,6 +153,23 @@ def output_text_verbatim(id: str, placeholder: bool = False) -> Tag:
 
 @add_example()
 def output_table(id: str, **kwargs: TagAttrArg) -> Tag:
+    """
+    Create a output container for a table.
+
+    Parameters
+    ----------
+    id
+        An input id.
+    **kwargs
+        Additional attributes to add to the container.
+
+    Returns
+    -------
+
+    See Also
+    -------
+    ~shiny.render.table
+    """
     return tags.div({"class": "shiny-html-output"}, id=resolve_id(id), **kwargs)