From b990bcb67a01c40e9edd0e415170aae5d5997b26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A1bio=20Rosado?= <fabioglrosado@gmail.com>
Date: Tue, 15 Nov 2022 15:35:50 +0000
Subject: [PATCH] Add basic docs for py-terminal (#933)

* Add basic docs for py-terminal

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add Antonio's suggestions

* Remove terminal = true

* fix typo

Co-authored-by: Antonio Cuni <anto.cuni@gmail.com>

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Antonio Cuni <anto.cuni@gmail.com>
---
 docs/reference/index.md               | 10 +++++++
 docs/reference/plugins/py-terminal.md | 41 +++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/reference/plugins/py-terminal.md

diff --git a/docs/reference/index.md b/docs/reference/index.md
index 6fe0efd9..0de64d5f 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -17,6 +17,16 @@ caption: Modules
 ---
 modules/*
 ```
+
+```{toctree}
+---
+maxdepth: 1
+glob:
+caption: Plugins
+---
+plugins/*
+```
+
 ```{toctree}
 ---
 maxdepth: 1
diff --git a/docs/reference/plugins/py-terminal.md b/docs/reference/plugins/py-terminal.md
new file mode 100644
index 00000000..0bea2d3d
--- /dev/null
+++ b/docs/reference/plugins/py-terminal.md
@@ -0,0 +1,41 @@
+# &lt;py-terminal&gt;
+
+This is one of the core plugins in PyScript, which is active by default. With it, you can print to `stdout` and `stderr` from your python code, and the output will be displayed on the page in `<py-terminal>`.
+
+## Configuration
+
+You can control how `<py-terminal>` behaves by setting the value of the  `terminal` configuration in your `<py-config>`.
+
+| value | description |
+|-------|-------------|
+| `false` | Don't add `<py-terminal>` to the page |
+| `true` | Automatically add a `<py-terminal>` to the page |
+| `"auto"` | This is the default. Automatically add a `<py-terminal auto>`, to the page. The terminal is initially hidden and automatically shown as soon as something writes to `stdout` and/or `stderr` |
+
+### Examples
+
+```html
+<py-config>
+    terminal = true
+</py-config>
+
+<py-script>
+    print("Hello, world!")
+</py-script>
+```
+
+This example will create a new `<py-terminal>`, the value "Hello, world!" that was printed will show in it.
+
+You can also add one (or more) `<py-terminal>` to the page manually.
+
+```html
+<py-script>
+    print("Hello, world!")
+</py-script>
+
+<py-terminal></py-terminal>
+```
+
+```{note}
+If you include a `<py-terminal>` in the page, you can skip `terminal` from your `<py-config>`.
+```