lay down the features page sections

.gitignore

@@ -73,6 +73,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/_env/
+newdocs/_env/
 
 # PyBuilder
 target/

docs/index.md

@@ -2,11 +2,24 @@
 
 Welcome to the PyScript documentation!
 
-PyScript provides a way for you to run Python code directly in your browser, giving
+PyScript is a programming platform that allows you to create web applications that run in the browser, using Python.
-anyone the ability to program without infrastructure barriers. Add an interactive
+That creates some really interesting benefits:
-Python REPL directly to your website, share an interactive dashboard with a colleague
+
-as an HTML file, or create a client-side Python-powered web application. This documentation
+* Using Python directly in the browser allows to create applications with an easier and more user friendly language
-will show you how.
+* Scalability: since applications run directly in the browser and not on a server somewhere, servers don't need to
+scale as much if the number of users of an application grows exponentially
+* Shareability: applications can be shared as easily as sharing an URL. Can't get easier than that ;)
+* Multi-Platform support: since the browser is the underlying system where PyScript applications run, applications
+can run anywhere a modern browser is installed, on windows, linux, mac, mobile, or even a Tesla! :)
+* Security: since PyScript runs core in the Browser (via Web Assembly) in a sandbox fashion and the browsers offers
+a very strict level of security, code never have access files or part of the underlying system without user permission,
+making it a great option in terms of security.
+* User Friendly APIs: web APIs are very vast and, sometimes, complicated. PyScript offers smaller and more user friendly
+APIs for the most common use cases while also providing an option to access the full Web APIs as well.
+
+We hope you'll enjoy the project and create so many incredible things with it! To learn more, consult our documentation.
+
+
 
 ::::{grid} 2
 :gutter: 3

docs/tutorials/getting-started.md

@@ -1,56 +1,93 @@
 # Getting started with PyScript
 
-This page will guide you through getting started with PyScript.
+To start developing a PyScript, like with most applications development, you need a **development environment** where you
+write your code, a way to install the programming libraries and dependencies your code needs, and way to build and distribute
+your application.
+
+Luckily, PyScript makes many of these steps much easier.
 
 ## Development setup
 
-PyScript does not require any development environment other
+PyScript does not require any specific development environment other
 than a web browser (we recommend using [Chrome](https://www.google.com/chrome/)) and a text editor, even though using your [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) of choice might be convenient.
 
 If you're using [VSCode](https://code.visualstudio.com/), the
 [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)
 can be used to reload the page as you edit the HTML file.
 
+**NOTE:** The easier way to get a development setup for PyScript is to use [pyscript.com](pyscript.com). It is a free service that allows
+users to create new projects from pre-created templates that already have all the project structure created and allows users
+to edit their apps, preview it and deploy with just a link, all in the same place.
+
 ## Installation
 
-There is no installation required. In this document, we'll use
+There is no PyScript specific installation required in your system to start using PyScript in your browser. All you need to do is to
-the PyScript assets served on [https://pyscript.net](https://pyscript.net).
+simply add a reference in your application code to where your application should get PyScript from.
 
-If you want to download the source and build it yourself, follow
+If you are not an experienced developer and it all sounds very complicated, don't worry, we'll get you through it in the following steps.
-the instructions in the [README.md](https://github.com/pyscript/pyscript/blob/main/README.md) file.
 
-## Your first PyScript HTML file
+## Writing your first PyScript application
 
-Here's a "Hello, world!" example using PyScript.
+As we hinted earlier, writing a PyScript application means writing a web application that can run code writted in Python (and other languages)
+on the web. This means that the way we create PyScript applications starts in a very similar way to how we write web applications: from an
+HTML file.
 
-Using your favorite editor, create a new file called `hello.html` in
+To demonstrate the above, let's start from the most popular "first application example": let's write a "Hello, world!"
-the same directory as your PyScript, JavaScript, and CSS files with the
+example using PyScript.
-following content, and open the file in your web browser. You can typically
+
-open an HTML by double-clicking it in your file explorer.
+Using your favorite editor, create a new file called `hello.html` and paste in the following content and open it in your web browser. (You can typically
+open an HTML by double-clicking it in your file explorer.):
 
 ```html
+<!DOCTYPE html>
 <html>
   <head>
-    <link rel="stylesheet" href="https://pyscript.net/latest/pyscript.css" />
+      <meta charset="utf-8" />
-    <script defer src="https://pyscript.net/latest/pyscript.js"></script>
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
+
+      <title>My First PyScript APP: Hello World!</title>
+      <script
+          type="module"
+          src="https://esm.sh/@pyscript/core@latest/core.js"
+      ></script>
   </head>
   <body>
     <py-script>
+        from pyscript import display
         print('Hello, World!')
+        display('Hello, World!')
     </py-script>
   </body>
 </html>
 ```
 
-### Using a Local Server
+<a href="https://fpliger.pyscriptapps.com/hello-world-minimal-example/latest/" target="_blank">or open this example on pyscript.com</a>
 
-In some situations, your browser may forbid loading remote resources like `pyscript.js` and `pyscript.css` when you open an HTML file directly. When this is the case, you may see your Python code in the text of the webpage, and the [browser developer console](https://balsamiq.com/support/faqs/browserconsole/) may show an error like *"Cross origin requests are only supported for HTTP."* The fix for this is to use a [simple local server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/set_up_a_local_testing_server) to make your html file available to the browser.
+You should see "Hello World!" printed in your page and in your Javascript Console (don't worry if
+you don't know what it means yet, we'll get into that later).
 
-If you have python installed on your system, you can use it's basic built-in server for this purpose via the command line. Change the current working directory of your terminal or command line to the folder where your HTML file is stored. From this folder, run `python -m http.server 8080 --bind 127.0.0.1` in your terminal or command line. With the server program running, point your browser to `http://localhost:8080` to view the contents of that folder. (If a file in that folder is called `index.html`, it will be displayed by default.)
+## Serving your application
+
+Now what we have written our first application, it's important talk about how we can access it.
+
+In the example above, we were able to visualize it by simply opening the local file from our
+system directly with the browser. While that's a very simple and fast way to open our application,
+it is not very recommended because browsers will forbid many features when accessing files this way,
+for security reasons. When this is the case, you may see your Python code in the text of the webpage,
+and the [browser developer console](https://balsamiq.com/support/faqs/browserconsole/) may show an
+error like *"Cross origin requests are only supported for HTTP."*
+
+In short, when browsers visualize a web page, they expect them to be served by a
+web server.
+
+For the rest of this documentation, we'll be presenting examples and snippets and host them on
+pyscript.com. Users can reference the [serving your application](serving-your-application.md) at
+anytime for other options.
 
 ## A more complex example
 
-Now that we know how you can create a simple 'Hello, World!' example, let's see a more complex example. This example will use the Demo created by [Cheuk Ting Ho](https://github.com/Cheukting). In this example, we will use more features from PyScript.
+Now that we know how you can create a simple 'Hello, World!' example, let's see a more complex example.
+This example will use the Demo created by [Cheuk Ting Ho](https://github.com/Cheukting). In this example, we will use more features from PyScript.
 
 ### Setting up the base index file
 

newdocs/Makefile

@@ -0,0 +1,46 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+CONDA_ENV     ?= _env
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+env := $(CONDA_ENV)
+conda_run := conda run -p $(env)
+
+setup:
+	@if [ -z "$${CONDA_SHLVL:+x}" ]; then echo "Conda is not installed." && exit 1; fi
+	$(CONDA_EXE) env $(shell [ -d $(env) ] && echo update || echo create) -p $(env) --file environment.yml
+
+clean:
+	rm -rf $(BUILDDIR)
+
+clean-all: clean
+	rm -rf $(env) *.egg-info
+
+shell:
+	@export CONDA_ENV_PROMPT='<{name}>'
+	@echo 'conda activate $(env)'
+
+htmlserve: html
+	@echo 'visit docs at http://localhost:8080'
+	python -m http.server -d "$(BUILDDIR)/html/" 8080
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+.PHONY: help Makefile setup clean clean-all shell
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

newdocs/README.md

@@ -0,0 +1,56 @@
+# PyScript documentation
+
+Welcome to the PyScript documentation directory, where you can find
+and contribute to discussions around PyScript and related topics.
+
+## Getting started
+
+Before you start contributing to the documentation, it's worthwhile to
+take a look at the general contributing guidelines for the PyScript project. You can find these guidelines here
+[Contributing Guidelines](https://github.com/pyscript/pyscript/blob/main/CONTRIBUTING.md)
+
+## Documentation Principles
+
+The PyScript documentation is based on a documentation framework called [Diátaxis](https://diataxis.fr/). This framework helps to solve the problem of structure in technical documentation and identifies four modes of documentation - **tutorials, how-to guides, technical reference and explanation**. Each one of these modes answers to a different user need, fulfills a different purpose and requires a different approach to its creation.
+
+The picture below gives a good visual representation of that separation of concerns:
+
+![pyodide-pyscript](./img/diataxis.png)
+
+So, please keep that in mind when contributing to the project documentation. For more information on, make sure to check [their website](https://diataxis.fr/).
+
+### Setup
+
+The `docs` directory in the pyscript repository contains a
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) documentation project. Material is a system
+that takes plaintext files containing documentation written in Markdown, along with
+static files like templates and themes, to build the static end result.
+
+To setup the documentation development environment simply run `make setup` from this folder and, once it's done,
+activate your environment by running `conda activate ./_env`
+
+### Build
+
+Simply run `mkdocs serve`
+
+## Cross-referencing
+
+You can link to other pages in the documentation by using the `{doc}` role. For example, to link to the `docs/README.md` file, you would use:
+
+```markdown
+{doc}`docs/README.md`
+```
+
+You can also cross-reference the python glossary by using the `{term}` role. For example, to link to the `iterable` term, you would use:
+
+```markdown
+{term}`iterable`
+```
+
+You can also cross-reference functions, methods or data attributes by using the `{attr}` for example:
+
+```markdown
+{py:func}`repr`
+```
+
+This would link to the `repr` function in the python builtins.

newdocs/docs/advanced-user-guide.md

@@ -0,0 +1 @@
+# Advanced User Guide

newdocs/docs/assets/images/pyscript-black.svg

@@ -0,0 +1,16 @@
+<svg width="100%" viewBox="0 0 2057 974" xmlns="http://www.w3.org/2000/svg">
+    <g fill="#000000" stroke="none" transform="translate(0 100)">
+        <path
+            d="M 1092.534 158.364 C 1095.764 169.589 1102.374 179.795 1107.224 190.364 C 1119.104 216.243 1131.874 241.728 1144.274 267.364 C 1179.204 339.56 1214.064 411.844 1248.314 484.364 C 1260.474 510.112 1273.154 535.617 1285.314 561.364 C 1290.014 571.319 1299.154 583.378 1300.684 594.364 C 1301.444 599.785 1296.944 606.478 1294.984 611.364 C 1289.004 626.289 1282.004 640.557 1273.734 654.364 C 1265.284 668.483 1256.704 683.257 1245.444 695.364 C 1237.304 704.123 1228.664 712.851 1218.534 719.31 C 1176.654 746.023 1130.104 739.811 1084.534 729.364 L 1084.534 796.364 C 1137.744 803.235 1191.744 806.988 1241.534 782.094 C 1291.224 757.25 1321.144 708.125 1345.794 660.364 C 1391.424 571.949 1425.474 477.074 1463.954 385.364 C 1484.774 335.759 1505.144 285.968 1525.954 236.364 C 1532.804 220.048 1539.454 203.643 1546.384 187.364 C 1550.314 178.14 1555.824 168.274 1557.534 158.364 L 1503.534 158.364 C 1498.104 158.364 1487.624 156.363 1482.924 159.392 C 1477.284 163.031 1474.824 176.375 1472.254 182.364 C 1463.294 203.198 1455.174 224.401 1446.524 245.364 C 1422.624 303.289 1398.764 361.248 1375.334 419.364 C 1365.024 444.923 1349.894 471.569 1343.534 498.364 L 1341.534 498.364 L 1326.784 467.364 L 1300.794 414.364 L 1219.784 248.364 L 1188.284 184.364 L 1174.894 159.392 L 1152.534 158.364 L 1092.534 158.364 Z">
+        </path>
+        <path
+            d="M 100.534 391.364 C 109.625 398.897 122.97 403.329 133.534 408.611 L 197.534 440.611 L 405.534 544.611 C 436.606 560.147 467.458 576.073 498.534 591.611 C 511.98 598.334 527.713 609.722 542.534 612.364 L 542.534 563.364 L 541.506 543.754 L 518.534 531.117 L 460.534 502.117 L 307.534 425.117 L 240.534 391.364 L 307.534 358.117 L 459.534 282.611 L 518.534 253.117 L 541.506 240.727 L 542.534 221.364 L 542.534 171.364 C 527.073 174.12 510.565 186.102 496.534 193.117 L 398.534 242.117 L 200.534 341.117 C 167.367 357.701 132.553 372.676 100.534 391.364 Z">
+        </path>
+        <path
+            d="M 1600.534 171.364 L 1600.534 220.364 C 1600.534 225.605 1598.654 235.422 1601.564 239.974 C 1605.194 245.662 1617.614 249.159 1623.534 252.117 L 1680.534 280.611 C 1730.924 305.806 1781.134 331.41 1831.534 356.611 C 1853.974 367.829 1877.404 384.412 1901.534 391.364 L 1901.534 393.364 C 1875.624 400.829 1849.674 418.049 1825.534 430.117 L 1679.534 503.117 C 1661.964 511.903 1644.564 521.567 1626.534 529.364 C 1619.964 532.203 1605.494 536.596 1601.564 542.754 C 1598.654 547.306 1600.534 557.122 1600.534 562.364 L 1600.534 612.364 L 1655.534 585.611 L 1763.534 531.611 L 1947.534 439.611 L 2041.534 392.364 C 2031.474 382.202 2012.324 376.511 1999.534 370.117 L 1907.534 324.117 L 1701.534 221.117 L 1635.534 188.117 C 1624.294 182.495 1612.624 174.847 1600.534 171.364 Z">
+        </path>
+        <path
+            d="M 704.534 384.364 C 704.534 374.13 702.051 360.064 705.503 350.364 C 710.589 336.071 722.183 321.459 731.164 309.364 C 737.516 300.809 743.992 292.429 750.959 284.364 C 786.81 242.863 854.576 189.488 905.519 239.403 C 931.848 265.201 939.204 301.065 941.623 336.364 C 946.631 409.413 926.04 491.22 860.534 532.928 C 811.862 563.917 757.912 556.382 704.534 545.364 Z M 705.534 259.364 L 704.534 259.364 L 704.534 158.364 L 628.534 158.364 L 628.534 789.364 L 704.534 789.364 L 704.534 613.364 C 728.157 613.38 751.915 618.29 775.534 619.325 C 816.206 621.106 857.009 614.508 893.534 596.116 C 989.069 548.011 1025.008 434.77 1024.535 335.364 C 1024.298 285.5 1013.766 232.452 979.364 194.364 C 968.209 182.013 954.851 171.287 940.534 162.816 C 875.388 124.27 794.704 158.21 745.534 207.364 C 730.887 222.007 713.84 240.114 705.534 259.364 Z">
+        </path>
+    </g>
+</svg>

newdocs/docs/assets/images/pyscript.svg

@@ -0,0 +1,16 @@
+<svg width="100%" viewBox="0 0 2057 974" xmlns="http://www.w3.org/2000/svg">
+    <g fill="#fda703" stroke="none" transform="translate(0 100)">
+        <path
+            d="M 1092.534 158.364 C 1095.764 169.589 1102.374 179.795 1107.224 190.364 C 1119.104 216.243 1131.874 241.728 1144.274 267.364 C 1179.204 339.56 1214.064 411.844 1248.314 484.364 C 1260.474 510.112 1273.154 535.617 1285.314 561.364 C 1290.014 571.319 1299.154 583.378 1300.684 594.364 C 1301.444 599.785 1296.944 606.478 1294.984 611.364 C 1289.004 626.289 1282.004 640.557 1273.734 654.364 C 1265.284 668.483 1256.704 683.257 1245.444 695.364 C 1237.304 704.123 1228.664 712.851 1218.534 719.31 C 1176.654 746.023 1130.104 739.811 1084.534 729.364 L 1084.534 796.364 C 1137.744 803.235 1191.744 806.988 1241.534 782.094 C 1291.224 757.25 1321.144 708.125 1345.794 660.364 C 1391.424 571.949 1425.474 477.074 1463.954 385.364 C 1484.774 335.759 1505.144 285.968 1525.954 236.364 C 1532.804 220.048 1539.454 203.643 1546.384 187.364 C 1550.314 178.14 1555.824 168.274 1557.534 158.364 L 1503.534 158.364 C 1498.104 158.364 1487.624 156.363 1482.924 159.392 C 1477.284 163.031 1474.824 176.375 1472.254 182.364 C 1463.294 203.198 1455.174 224.401 1446.524 245.364 C 1422.624 303.289 1398.764 361.248 1375.334 419.364 C 1365.024 444.923 1349.894 471.569 1343.534 498.364 L 1341.534 498.364 L 1326.784 467.364 L 1300.794 414.364 L 1219.784 248.364 L 1188.284 184.364 L 1174.894 159.392 L 1152.534 158.364 L 1092.534 158.364 Z">
+        </path>
+        <path
+            d="M 100.534 391.364 C 109.625 398.897 122.97 403.329 133.534 408.611 L 197.534 440.611 L 405.534 544.611 C 436.606 560.147 467.458 576.073 498.534 591.611 C 511.98 598.334 527.713 609.722 542.534 612.364 L 542.534 563.364 L 541.506 543.754 L 518.534 531.117 L 460.534 502.117 L 307.534 425.117 L 240.534 391.364 L 307.534 358.117 L 459.534 282.611 L 518.534 253.117 L 541.506 240.727 L 542.534 221.364 L 542.534 171.364 C 527.073 174.12 510.565 186.102 496.534 193.117 L 398.534 242.117 L 200.534 341.117 C 167.367 357.701 132.553 372.676 100.534 391.364 Z">
+        </path>
+        <path
+            d="M 1600.534 171.364 L 1600.534 220.364 C 1600.534 225.605 1598.654 235.422 1601.564 239.974 C 1605.194 245.662 1617.614 249.159 1623.534 252.117 L 1680.534 280.611 C 1730.924 305.806 1781.134 331.41 1831.534 356.611 C 1853.974 367.829 1877.404 384.412 1901.534 391.364 L 1901.534 393.364 C 1875.624 400.829 1849.674 418.049 1825.534 430.117 L 1679.534 503.117 C 1661.964 511.903 1644.564 521.567 1626.534 529.364 C 1619.964 532.203 1605.494 536.596 1601.564 542.754 C 1598.654 547.306 1600.534 557.122 1600.534 562.364 L 1600.534 612.364 L 1655.534 585.611 L 1763.534 531.611 L 1947.534 439.611 L 2041.534 392.364 C 2031.474 382.202 2012.324 376.511 1999.534 370.117 L 1907.534 324.117 L 1701.534 221.117 L 1635.534 188.117 C 1624.294 182.495 1612.624 174.847 1600.534 171.364 Z">
+        </path>
+        <path
+            d="M 704.534 384.364 C 704.534 374.13 702.051 360.064 705.503 350.364 C 710.589 336.071 722.183 321.459 731.164 309.364 C 737.516 300.809 743.992 292.429 750.959 284.364 C 786.81 242.863 854.576 189.488 905.519 239.403 C 931.848 265.201 939.204 301.065 941.623 336.364 C 946.631 409.413 926.04 491.22 860.534 532.928 C 811.862 563.917 757.912 556.382 704.534 545.364 Z M 705.534 259.364 L 704.534 259.364 L 704.534 158.364 L 628.534 158.364 L 628.534 789.364 L 704.534 789.364 L 704.534 613.364 C 728.157 613.38 751.915 618.29 775.534 619.325 C 816.206 621.106 857.009 614.508 893.534 596.116 C 989.069 548.011 1025.008 434.77 1024.535 335.364 C 1024.298 285.5 1013.766 232.452 979.364 194.364 C 968.209 182.013 954.851 171.287 940.534 162.816 C 875.388 124.27 794.704 158.21 745.534 207.364 C 730.887 222.007 713.84 240.114 705.534 259.364 Z">
+        </path>
+    </g>
+</svg>

newdocs/docs/contributing.md

@@ -0,0 +1 @@
+# Contributing

newdocs/docs/features.md

@@ -0,0 +1,38 @@
+# What is PyScript - Features
+
+PyScript is a software platform that combines the power of the web with the power and simplicity
+of the most popular programming language in the world to provide an ecosystem that let users create
+and distribute applications in seconds, while having fun.
+
+
+## How does it work?
+
+The PyScript library provides HTML tags for embedding and executing Python code in your browser. PyScript is built using Pyodide, the WebAssembly port of CPython, which is compiled using Emscripten.
+
+PyScript turns the browser into a code deployment tool that anyone can learn to use.
+
+Example
+In this example, we are using the <py-script> HTML tag to generate a Matplotlib figure and display it as an image. Click Preview to see the rendered HTML.
+
+To try it in your browser, copy the code below into an online HTML editor like W3School’s Tryit Editor, which allows you to modify, run, and even save your code. Watch the video below to see it in action!
+
+
+## Features
+
+### Run Python code in the browser
+
+#### In the main thread
+
+#### In a web worker
+
+### Environment Setup
+
+#### Install Python Packages
+
+#### Download files and assets
+
+### Error reporting
+
+### Pythonic Web APIs
+
+### Access to Javascript

newdocs/docs/getting-started.md

@@ -0,0 +1,349 @@
+# Getting started with PyScript
+
+To start developing a PyScript, like with most applications development, you need a **development environment** where you
+write your code, a way to install the programming libraries and dependencies your code needs, and way to build and distribute
+your application.
+
+Luckily, PyScript makes many of these steps much easier.
+
+## Requirements
+
+To visualize a PyScript application, users only need a modern web browser.
+
+To distribute a PyScript application, the only requirement is for the application to be hosted somewhere a browser can reach.
+
+To create a PyScript application, users need a Development Environment, often also called [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment)
+where they can write their code.
+
+
+**Note:** The easiest way to get the a full PyScript development environment and application hosting setup in seconds,
+is to use [pyscript.com](pyscript.com) on your browser. It is a free service that helps users create new projects from
+pre-created templates already structured using best practices allowing user to edit, preview and deploy their apps with
+just a link, all in the same place.
+
+
+### Development Environment
+
+Like most software platforms, PyScript requires a development environment where the user can write their applications. This
+means an editor where to edit files, installing all dependencies needed by the application and setting everything up so
+that the application can be build and distributed. PyScript simplify these aspects for the user, reducing these needs to
+an editor, a browser and ways to serve your application files.
+
+PyScript does not require any specific development environment other than a web browser (we recommend using
+[Chrome](https://www.google.com/chrome/)) and a text editor ([IDE](https://en.wikipedia.org/wiki/Integrated_development_environment))
+that authors can use to write their applications. Users are free to choose according to their preference. We recommend
+picking youR favorite browser and IDE, or using pyscript.com (that includes an editor in the browser itself).
+
+**Note:** If you're using [VSCode](https://code.visualstudio.com/), the
+[Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)
+can be used to reload the page as you edit the HTML file.
+
+## Installation
+
+There is no PyScript specific installation required in your system to start using PyScript in your browser. All you need to do is to
+simply add a reference in your application code to where your application should get PyScript from.
+
+If you are not an experienced developer and it all sounds very complicated, don't worry, we'll get you through it in the following steps.
+
+### Application Development Phases
+
+Just like with any Web Application, the development lifecycle of an application in 2 phases:
+
+* **development:** this is where authors write their files and application logic
+* **deployment:** in order to open your application in a browser, your application files need to be
+"uploaded" to a web server that is able to share your application with the right format when
+it's requested by a browser. This is also deferret to as "serving" web page.
+
+Before we get into the `development` topic and have some fine writing our first applications, let's talk about
+how to serve a pyscript application.
+
+## Serving your application
+
+
+While browsers are also capable of opening files from the users local system, it is not recommended because,
+for security reasons, browsers will forbid and disable many features when accessing files this way.
+(In this is the case, you may see your Python code in the text of the webpage, and the
+[browser developer console](https://balsamiq.com/support/faqs/browserconsole/) may show an
+error like *"Cross origin requests are only supported for HTTP."*)
+
+In short, when browsers visualize a web page, they expect them to be served by a
+web server.
+
+### Serving your application from your computer
+
+There are many ways you can initiate a local web server to serve files. We'll only cover one of them,
+using `Python`.
+
+Assuming you have `Python` installed in your system, `cd` in your application folder and run
+the following python command:
+
+```python
+python3 -m http.server
+```
+
+### Serving your application from a web server
+
+If there are many ways to serve a web application from your computer, there are many more
+options on how to serve your application from a hosting service on the internet. We will not cover
+this in detail and only suggest users to look into:
+
+* pyscript.com as it's a free service and makes the process of authoring and serving an
+application almost transparent.
+* github pages as it's a free service and Github is a very popular service adopted by developers.
+
+
+For the rest of this documentation, we'll be presenting examples and snippets and host them on
+pyscript.com.
+
+
+## Basic Application Concepts
+
+While we'll cover PyScript concepts and APIs more thoroughly in the PyScript Concepts and PyScript User Guide sections, it's important
+to understand the basics.
+
+PyScript is a Software Platform that enables users to write Python Applications that run in the Browser, with a simple and user
+friendly interface. For this reason, it aims to have a small and intuitive interface that triest to enable users while staying out of
+the way. In fact, there are 3 main parts of a PyScript application:
+
+1. **Presentation:** Usually this is managed in a `html` file and is also where we specify that `PyScript`` needs
+to be loaded into the application.
+2. **Configuration:** where users can define their dependencies, assets to be downloaded, etc. PyScript configuration
+files in `TOML` or `JSON` formats
+3. **Code Logic:** These are typically Python files that host the application code. PyScript allows users to run these
+through special `html` tags (such as `<script type="py">` or `<py-script>`) properly placed in their `html` file.
+
+The `html` file acts as the entry point and center of gravity of an application.
+
+
+## Writing your first PyScript application
+
+As we hinted earlier, writing a PyScript application means writing a web application that
+can run code writted in Python (and other languages) on the web. This means that creating
+PyScript applications starts in a very similar way to web applications: from an `html` file.
+
+Let's start from the most basic and popular "first application example" possible, a
+"Hello, world!" application! In this case we will:
+
+1. Write an `html` file that is the main entry point for our application.
+2. Load `pyscript` in our application by using: `<script type="module" src="https://esm.sh/@pyscript/core@latest/core.js"></script>`
+3. Skip a configuration file for our projects and use the default since we won't need to install any additional dependencies.
+4. Add a `<py-script>` tag to use as entrypoint for our Python code, that will be executed when the page loads.
+
+**NOTE:** We highly recommend users to reproduce and interact with the examples below on their own on pyscript.com or
+with their favorite Development Environment setup.
+
+First, create a new file called `hello.html` and paste in the following content and open it in your web browser.
+
+**Hint:** In the example below, click on the ➕ icon to read hints about specific sections in the code examples
+
+```html title="hello_world.html"
+<!DOCTYPE html>
+<html>
+  <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
+
+      <title>My First PyScript APP: Hello World!</title>
+      <script type="module" src="https://esm.sh/@pyscript/core@latest/core.js"></script> <!-- (1) Load PyScript -->
+  </head>
+  <body>
+    <!-- (2) In this case were using the default config, so don't need to specify a `<py-config>` tag -->
+
+    <!-- (3) run the code in the `main.py` file -->
+    <py-script src="main.py"></py-script>
+  </body>
+</html>
+```
+
+1.  ⚡️ we use a `<script>` tag to load `PyScript` in the `head` of our `HTML` document so it can
+    load as soon as possible
+2.  if needed to install any packages we could load a config in this point, so that any python code
+    can have their dependencies installed before they run
+3.  🐍 the code in `main.py` will run inside the default `Python` interpreter as soon as it's ready
+
+and create a new `main.py` file with the following code:
+
+```python title="main.py"
+from pyscript import display # (1)
+print('Hello, World!') # print "Hello, World!" to the console
+display('Hello, World!') # displays "Hello, World!" in the main page
+```
+
+1.  pyscript provides the `display` funcition that can be used to display any variable on the page,
+    while the Python `print` statement will automatically print objects on the browser `console`.
+
+<a href="https://fpliger.pyscriptapps.com/hello-world-minimal-example/latest/" class="md-button" target="_blank">open this example on pyscript.com</a>
+
+When you open application in your browser, you should see `Hello, World!` printed in your page and in your Javascript Console
+(if you are new to web development and don't know what it means yet, don't worry,t, we'll get into that later).
+
+Easy, right?
+
+### Using files vs. inline code
+
+In the example above we wrote our Python code for the application logic in a separate file called `main.py`.
+While this is a best practive and recommended, `PyScript` also allows users to write their code in the
+`html` file, within the `pyscript` tag. In this case, if we rewrote the same example in a single file using
+this feature, we'd have the following:
+
+```html title="hello_world.py"
+<!DOCTYPE html>
+<html>
+  <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
+
+      <title>My First PyScript APP: Hello World!</title>
+      <script type="module" src="https://esm.sh/@pyscript/core@latest/core.js"></script> <!-- Load PyScript -->
+  </head>
+  <body>
+    <!-- In this case were using the default config, so don't need to specify a `<py-config>` tag -->
+
+    <!-- (1) run the code that is defined within the <script type="py"> tag-->
+    <script type="py" src="main.py">
+      from pyscript import display # (1)
+      print('Hello, World!') # print "Hello, World!" to the console
+      display('Hello, World!') # displays "Hello, World!" in the main page
+    </script>
+  </body>
+</html>
+```
+1.  🐍 Noticed anything different? Yes, we are passing the python code within the tag itself instead
+of a separate `main.py` file.
+
+<a href="https://fpliger.pyscriptapps.com/hello-world-minimal-example/latest/" class="md-button" target="_blank">open this example on pyscript.com</a>
+
+If you noticed, above we are using `<script type="...">` instead of `<py-script>`. That is another way you
+can run code logic in PyScript. The reason we are using `script` in this case is that the `<py-script>`
+does not support inline code due to how the browser treats one vs. the other. For all use cases where
+the code is defined in a separate file, both tags are equivalent
+
+**⚠️ Important:** While very convenient, we recommend always defining your code in a separate
+`.py` file as a best practice for the following reasons:
+
+* editors don't have good support for inline code
+* it's really hard to test, lint or QA code define within tags
+* code can be easily exported
+* both your `html` and `python` code will be easier to read and better organized
+
+
+## A more complex example
+
+Now that we know how you can create a simple 'Hello, World!' example, let's use everything
+we've learned above  see a more complex example.
+
+### Setting up the base index file
+
+Just like before, let's create a new `html` file that will contain our application template
+and interface. We'll call this file `index.html` and add the following content:
+
+```html title="index.html"
+<!DOCTYPE html>
+<html>
+  <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
+
+      <title>Ice Cream Picker</title>
+      <script type="module" src="https://esm.sh/@pyscript/core@latest/core.js"></script> <!-- (1) Load PyScript -->
+  </head>
+  <body>
+    <py-config src="pyscript.toml"></py-config>
+
+    <!-- (3) run the code in the `main.py` file -->
+    <py-script src="main.py"></py-script>
+
+    <div id="input" style="margin: 20px;">
+      Select your 🍨 flavour: <br/>
+      <input type="radio" id="all" name="flavour" value="ALL">
+      <label for="all"> All 🍧</label>
+      <input type="radio" id="chocolate" name="flavour" value="COCOA">
+      <label for="chocolate"> Chocolate 🍫</label>
+      <input type="radio" id="cherry" name="flavour" value="CHERRIES">
+      <label for="cherry"> Cherries 🍒</label>
+      <input type="radio" id="berries" name="flavour" value="BERRY">
+      <label for="berries"> Berries 🍓</label>
+      <input type="radio" id="cheese" name="flavour" value="CHEESE">
+      <label for="cheese"> Cheese 🧀</label>
+      <input type="radio" id="peanut" name="flavour" value="PEANUT">
+      <label for="peanut"> Peanut 🥜</label>
+    </div>
+
+    <div id="graph-area"></div>
+  </body>
+</html>
+```
+
+This creates a solid base for our application and we are ready to start adding the elements we need for our application.
+
+### Importing the needed libraries
+
+For this example, we will need to install `pandas` and `matplotlib`. We can install libraries using the `<py-config>` tag
+we already added to the `index.html` file above. All we have to do now is to create the `pyscript.toml` file with the
+right dependencies:
+
+```toml title="pyscript.toml"
+packages = ["matplotlib", "pandas"]
+```
+
+For more information on the configuration files, please refer to the [`<py-config>` documentation](../reference/elements/py-config.md)
+
+### Importing and plotting the data
+
+Now that we have installed the needed libraries, we can import and explore the data. In this step, we need
+to create a `<py-script>` tag to import our dependencies, read the data with pandas and then use `py-repl`
+to explore the data.
+
+You may want to read the [`<py-script>`](../reference/elements/py-script.md) documentation for more information about it.
+
+
+```python title="main.py"
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from pyodide.http import open_url
+from pyodide.ffi import create_proxy
+from pyscript import display
+import js
+
+
+url = (
+    "https://raw.githubusercontent.com/Cheukting/pyscript-ice-cream/main/bj-products.csv"
+)
+ice_data = pd.read_csv(open_url(url))
+
+current_selected = []
+flavour_elements = js.document.getElementsByName("flavour")
+
+def plot(data):
+    plt.rcParams["figure.figsize"] = (22,20)
+    fig, ax = plt.subplots()
+    bars = ax.barh(data["name"], data["rating"], height=0.7)
+    ax.bar_label(bars)
+    plt.title("Rating of ice cream flavours of your choice")
+    display(fig, target="graph-area", append=False)
+
+def select_flavour(event):
+    for ele in flavour_elements:
+        if ele.checked:
+            current_selected = ele.value
+            break
+    if current_selected == "ALL":
+        plot(ice_data)
+    else:
+        filter = ice_data.apply(lambda x: ele.value in x["ingredients"], axis=1)
+        plot(ice_data[filter])
+
+ele_proxy = create_proxy(select_flavour)
+
+for ele in flavour_elements:
+    if ele.value == "ALL":
+      ele.checked = True
+      current_selected = ele.value
+    ele.addEventListener("change", ele_proxy)
+
+plot(ice_data)
+
+```
+
+<a href="https://fpliger.pyscriptapps.com/hello-world-minimal-example/latest/" class="md-button" target="_blank">open this example on pyscript.com</a>

newdocs/docs/index.md

@@ -0,0 +1,42 @@
+# PyScript
+
+![PyScript Logo](assets/images/pyscript.svg)
+
+<h3 style="text-align: center; font-style: italic;">The programming Platform for the 99%</h3>
+
+---------------------------------------------------------------------------------------------
+
+<p style="text-align: center; font-style: italic;">Welcome to the PyScript documentation!</p>
+
+PyScript is a programming platform that allows you to create web applications that run in
+the browser, using Python. That gives anyone the ability to program without infrastructure
+barriers and creates some really interesting benefits:
+
+* **Easy start**: create and share applications in the browser, not installation required
+* **Simplicity**: Code your apps with a friendly and intuitive language like Python
+* **Scalability**: since applications run directly in the browser and not on a server somewhere, servers don't need to
+scale as much if the number of users of an application grows exponentially
+* **Shareability**: applications can be shared as easily as sharing an URL. Can't get easier than that ;)
+* **Multi-Platform**: since the browser is the underlying system where PyScript applications run, applications
+can run anywhere a modern browser is installed, on windows, linux, mac, mobile, or even a Tesla! :)
+* **Security**: since PyScript runs core in the Browser (via Web Assembly) in a sandbox fashion and the browsers offers
+a very strict level of security, code never have access files or part of the underlying system without user permission,
+making it a great option in terms of security.
+* **User Friendly APIs**: web APIs are very vast and, sometimes, complicated. PyScript offers smaller and more user friendly
+APIs for the most common use cases while also providing an option to access the full Web APIs as well.
+
+We hope you'll enjoy the project and create so many incredible things with it! To learn more, consult our documentation.
+
+## What next?
+
+Check out our [getting started](getting-started.md) section to learn where to start from or go to our
+[user guide](user-guide.md) section for a more in-depth coverage of PyScript features.
+
+<div class="grid cards" markdown>
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+</div>

newdocs/docs/serving-your-application.md

@@ -0,0 +1,37 @@
+# Serving your application
+
+Now what we have written our first application, it's important talk about how we can access it.
+
+In the example above, we were able to visualize it by simply opening the local file from our
+system directly with the browser. While that's a very simple and fast way to open our application,
+it is not very recommended because browsers will forbid many features when accessing files this way,
+for security reasons. When this is the case, you may see your Python code in the text of the webpage,
+and the [browser developer console](https://balsamiq.com/support/faqs/browserconsole/) may show an
+error like *"Cross origin requests are only supported for HTTP."*
+
+In short, when browsers visualize a web page, they expect them to be served by a
+web server. Here are a few options that we can use to fix this issue:
+
+**NOTE:** If you are an experienced developer and already know how to host and serve files on a [static]
+web server, feel free to skip to the next section.
+
+TODO: It seems better to not go too deep into "how to serve a PyScript application" but to point to a dedicated
+section where we can add more options and actually point to other resources as well.
+
+### Using pyscript.com
+
+If you clicked on <a href="https://fpliger.pyscriptapps.com/hello-world-minimal-example/latest/" target="_blank">the link above</a>
+you've already saw how pyscript.com can be used to host PyScript applications.
+
+All you need to do is to create a free account and copy or start creating new projects.
+
+### Using a Local Server
+
+A very common fix for this is to use a [simple local server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/set_up_a_local_testing_server) to make your html file available to the browser.
+
+
+If you have python installed on your system, you can use it's basic built-in server for this purpose via the command line.
+Change the current working directory of your terminal or command line to the folder where your HTML file is stored.
+From this folder, run `python -m http.server 8080 --bind 127.0.0.1` in your terminal or command line. With the server
+program running, point your browser to `http://localhost:8080` to view the contents of that folder. (If a file in
+that folder is called `index.html`, it will be displayed by default.)

newdocs/docs/user-guide.md

@@ -0,0 +1 @@
+# User Guide

newdocs/environment.yml

@@ -0,0 +1,7 @@
+channels:
+    - conda-forge
+    - defaults
+dependencies:
+    - python=3.9
+    - pip=20.2.2
+    - mkdocs-material=9.2.6

newdocs/mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: PyScript
+
+theme:
+    name: material
+
+    logo: assets/images/pyscript-black.svg
+
+    palette:
+        # Palette toggle for automatic mode
+        - media: "(prefers-color-scheme)"
+          primary: orange
+          toggle:
+              icon: material/brightness-auto
+              name: Switch to light mode
+
+        # Palette toggle for light mode
+        - media: "(prefers-color-scheme: light)"
+          primary: orange
+          scheme: default
+          toggle:
+              icon: material/brightness-7
+              name: Switch to dark mode
+
+        # Palette toggle for dark mode
+        - media: "(prefers-color-scheme: dark)"
+          primary: orange
+          scheme: slate
+          toggle:
+              icon: material/brightness-4
+              name: Switch to system preference
+
+    features:
+        - content.code.copy
+        - content.code.annotate
+
+markdown_extensions:
+    - attr_list
+    - md_in_html
+    - pymdownx.highlight:
+          anchor_linenums: true
+          line_spans: __span
+          pygments_lang_class: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - pymdownx.superfences

newdocs/robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+Disallow: /review/
+
+Sitemap: https://docs.pyscript.net/sitemap.xml
+Host: docs.pyscript.net