From 643d41864ed3948dfea7a83bb4894263ccb6d17d Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Fri, 29 Sep 2023 16:25:47 +0100 Subject: [PATCH 1/2] Revisions for RC2 --- docs/beginning-pyscript.md | 6 +- docs/user-guide.md | 376 ++++++++++++++++++++++++++----------- 2 files changed, 272 insertions(+), 110 deletions(-) diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md index 99a1d5c4..8ce7f036 100644 --- a/docs/beginning-pyscript.md +++ b/docs/beginning-pyscript.md @@ -70,7 +70,7 @@ level. You can see this application embedded into the page below: - + Let's explore each of the three files that make this app work. @@ -106,7 +106,7 @@ module in the document's `` tag: 🦜 Polyglot - Piratical PyScript - + @@ -155,7 +155,7 @@ In the end, our HTML should look like this: 🦜 Polyglot - Piratical PyScript - +

Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️

diff --git a/docs/user-guide.md b/docs/user-guide.md index 7d5379c3..38c81587 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -7,7 +7,8 @@ While we endeavour to write clearly, some of the content in this user guide will not be suitable for beginners. We assume readers already have Python - or web development experience. + or web development experience. If you're a beginner start with our + [beginner's guide](/beginning-pyscript). We [welcome feedback](https://github.com/pyscript/docs/issues) to help us improve. @@ -19,14 +20,14 @@ This guide has three aims: 3. Demonstration of the features of PyScript working together in real-world example applications. -_Read this page in full_: you will acquire a comprehensive overview of the -PyScript platform along with suggestions for where next to explore and learn. +_Read this page in full_: it is a short but comprehensive overview of the +PyScript platform. -For more dynamic support, join in the PyScript conversation on our +Get involved! Join in the PyScript conversation on our [discord server](https://discord.gg/HxvBtukrg2). There you'll find core developers, community contributors and a flourishing forum for those creating projects with PyScript. Should you wish to engage with the development of -PyScript, you are welcome to engage and make contributions via +PyScript, you are welcome to contribute via [the project's GitHub organisation](https://github.com/pyscript). Finally, the examples listed at the end of this page are all freely available @@ -36,7 +37,7 @@ and copiously commented on [pyscript.com](pyscript.com). Many of these examples come from contributors in our wonderful community. If you believe you have a project that would make a good - demonstration example, please don't hesitate to + demonstration, please don't hesitate to [get in touch](https://discord.gg/HxvBtukrg2). ## What is PyScript? @@ -81,12 +82,12 @@ the planet who use computers. APIs implemented by your browser.

Thanks to the foreign - function interface (FFI), it is easy for Python to work within your - browser, including with third party JavaScript libraries that may be - included in the page.

+ function interface (FFI), Python just works with all the browser has to + offer, including any third party JavaScript libraries that may be included + in the page.

The FFI is bi-directional ~ it also enables JavaScript to access the - power of PyScript.

+ power of Python.

All of Python
@@ -99,27 +100,20 @@ the planet who use computers. efficient reimplementation of Python3 that includes a comprehensive subset of the standard library, compiled to WebAssembly. -
-

Warning

-

Currently, only Pyodide is enabled in PyScript.

-

This will change very soon once we complete our integration testing and - evaluation steps for MicroPython. However, the documentation relating - to MicroPython is currently correct and is included to indicate what - you have to look forward to.

-

Because it is just regular CPython, Pyodide puts Python's deep and diverse ecosystem of libraries, frameworks - and modules at your disposal. If you find yourself encountering some sort - of computing problem, there's probably a Python library to help you with - it. If you use a favourite library in Python, now you can use it in your - browser and share your work with ease via a URL.

+ and modules at your disposal. No matter the area of computing endeavour, + there's probably a Python library to help. Got a favourite library in + Python? Now you can use it in the browser and share your work with just + a URL.

MicroPython, because of its small size (170k) and speed, is especially suited to running on more constrained browsers, such as those on mobile or tablet devices. It includes a powerful sub-set of the Python standard library and efficiently exposes the expressiveness of Python to the browser.

-

Both Python interpreters supported by PyScript implement the same - FFI to bridge the gap between the worlds of Python and the browser.

+

Both Python interpreters supported by PyScript implement the + same FFI to bridge the gap between the worlds of Python + and the browser.

AI and Data science built in
@@ -140,25 +134,26 @@ the planet who use computers.
Thanks to a browser technology called web workers expensive and blocking computation can run somewhere other than the main - application thread that controls the user interface. When such work is done - on the main thread, the browser appears frozen. Web workers ensure - expensive blocking computation happens elsewhere. Think of workers as + application thread controlling the user interface. When such work is done + on the main thread, the browser appears frozen and web workers ensure + expensive blocking computation can happen elsewhere. Think of workers as independent subprocesses in your web page.
Rich and powerful plugins
-

As you'll see, PyScript has a small, efficient yet powerful core called - PolyScript.

-

Most of the functionality of PyScript is actually implemented through - PolyScript's plugin system.

+

PyScript has a small, efficient yet powerful core called + PolyScript. Most of + the functionality of PyScript is actually implemented through PolyScript's + plugin system.

-

This approach means we get a clear separation of concerns: PolyScript +

This approach ensures a clear separation of concerns: PolyScript can focus on being small, efficient and powerful, whereas the PyScript - related plugins allow us to build upon the generic features provided by + related plugins allow us to build upon the solid foundations of PolyScript.

-

More importantly, because there is a plugin system, folks - independent of the PyScript core team have a way to create their - own plugins so we get a rich ecosystem of functionality that reflects the + +

Because there is a plugin system, folks + independent of the PyScript core team have a way to create and + contribute to a rich ecosystem of plugins whose functionality reflects the unique and diverse needs of PyScript's users.

@@ -172,9 +167,8 @@ It's simple: For the browser to use PyScript, simply add a ` + @@ -197,10 +191,10 @@ attribute references a CDN url for `pyscript.core`, to your HTML document's There are two ways to tell PyScript how to find your code. * With a standard HTML ` ``` -...and here's the `` tag with inline Python code. +...and here's a `` tag with inline Python code. -```html title="Using the py-script tag with inline code" +```html title="Using a py-script tag with inline code" import sys from pyscript import display @@ -228,12 +222,7 @@ display(sys.version) ``` -The browser's tab displaying the website running PyScript is an isolated -computing sandbox. Define the Python environment in which your code will -run with [configuration options](#configuration) (discussed later in this -document). - -The ` +