docs: Update docs with preferred way of displaying documents #2291

website/docs/files.md

@@ -108,6 +108,17 @@ async def serve(q: Q):
 
 See `examples/file_stream.py` for a complete example.
 
+## Rendering documents
+
+Use `q.site.upload()` to upload document from your app to the Wave server (or see the following section for other ways for serving files). Use the returned paths in `ui.frame()` component.
+
+```py
+q.app.document_path, = await q.site.upload(['path/to/my/document.pdf'])
+q.page['example'] = ui.form_card(box='1 1 7 7', items=[
+    ui.frame(path=document_path)
+])
+```
+
 ## Serving files directly from the Wave server
 
 As an alternative to using the above `upload()` or `download()` mechanisms, you can make the Wave server (`waved`) directly serve the contents of one or more existing directories. If the Wave server and your app both have access to the directories on the file system, your app can simply create or copy files to the directories to make them accessible from web browsers.

website/widgets/form/frame.md

@@ -20,6 +20,16 @@ q.page['example'] = ui.form_card(box='1 1 7 7', items=[
 ])
 ```
 
+## With document
+
+The frame is also a preffered way for displaying documents. Simply provide a path to the PDF file.
+
+```py
+q.page['example'] = ui.form_card(box='1 1 7 7', items=[
+    ui.frame(path='/assets/examples/sample-document.pdf')
+])
+```
+
 ## With custom HTML
 
 For cases when you want to build the embedded page yourself, you can use the `content` attribute that