Fix broken links, add documentation updates.

ntoll · ntoll · commit ceacdb85493e · 2023-12-07T11:16:16.000Z
diff --git a/docs/beginning-pyscript.md b/docs/beginning-pyscript.md
@@ -139,7 +139,8 @@ application's output.
 
 There's something strange about the `<button>` tag: it has a `py-click`
 attribute with the value `translate_english`. This is, in fact, the name of a
-Python function we'll run whenever the button is clicked.
+Python function we'll run whenever the button is clicked. Such `py-*` style
+attributes are [built into PyScript](user-guide/builtins.md#html-attributes).
 
 We put all this together in the `script` tag at the end of the `<body>`. This
 tells the browser we're using PyScript (`type="py"`), and where PyScript
diff --git a/docs/index.md b/docs/index.md
@@ -34,10 +34,10 @@
   <dt><strong>I want to contribute...</strong></dt>
   <dd>
     <p>Welcome, friend!
-    PyScript is an <a href="/license/">open source project</a>, we expect participants to act in
-    the spirit of our <a href="/conduct/">code of conduct</a> and we have many 
-    ways in which <a href="/contributing/"><u>you</u> can contribute</a>.
-    Our <a href="/developers/">developer guide</a> explains how to set
+    PyScript is an <a href="license/">open source project</a>, we expect participants to act in
+    the spirit of our <a href="conduct/">code of conduct</a> and we have many 
+    ways in which <a href="contributing/"><u>you</u> can contribute</a>.
+    Our <a href="developers/">developer guide</a> explains how to set
     up a working development environment for PyScript.</p>
   </dd>
   <dt><strong>Just show me...</strong></dt>
diff --git a/docs/user-guide/architecture.md b/docs/user-guide/architecture.md
@@ -129,7 +129,7 @@ Here's how PyScript unfolds through time:
        attribute of a `<script>`, `<py-script>` or `<mpy-script>` tag).
     3. Given the detected configuration, download the required interpreter.
     4. Setup the interpreter's environment. This includes any
-       [plugins](configuration.md/#plugins), [packages](configuration.md/#packages) or [files](configuration.md/#files) that need
+       [plugins](configuration.md/#plugins), [packages](configuration.md/#packages), [files](configuration.md/#files) or [JavaScript modules](configuration.md/#javascript-modules)that need
        to be loaded.
     5. Make available various
        [builtin helper objects and functions](builtins.md) to the
diff --git a/docs/user-guide/builtins.md b/docs/user-guide/builtins.md
@@ -1,16 +1,24 @@
 # Builtin helpers
 
 PyScript makes available convenience objects and functions inside
-Python. This is done via the `pyscript` module:
+Python as well as custom attributes in HTML.
+
+In Python this is done via the `pyscript` module:
 
 ```python title="Accessing the document object via the pyscript module"
 from pyscript import document
 ```
 
+In HTML this is done via `py-*` attributes:
+
+```html title="An example of a py-click handler"
+<button id="foo" py-click="handler_defined_in_python">Click me</button>
+```
+
 ## Common features
 
-These objects / functions are available in both the main thread and in code
-running on a web worker:
+These Python objects / functions are available in both the main thread and in
+code running on a web worker:
 
 ### `pyscript.window`
 
@@ -94,6 +102,8 @@ def click_handler(event):
     display("I've been clicked!")
 ```
 
+This functionality is related to the [HTML py-*](#html-attributes) attributes.
+
 ### `pyscript.js_modules`
 
 It is possible to [define JavaScript modules to use within your Python code](configuration.md#javascript-modules).
@@ -152,3 +162,53 @@ from pyscript import sync
 
 sync.hello("PyScript")
 ```
+
+## HTML attributes
+
+As a convenience, and to ensure backwards compatibility, PyScript allows the
+use of inline event handlers via custom HTML attributes.
+
+!!! warning
+
+    This classic pattern of coding (inline event handlers) is no longer
+    considered good practice in web development circles.
+
+    We include this behaviour for historic reasons, but the folks at
+    Mozilla [have a good explanation](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#inline_event_handlers_%E2%80%94_dont_use_these)
+    of why this is currently considered bad practice.
+
+These attributes are expressed as `py-*` attributes of an HTML element that
+reference the name of a Python function to run when the event is fired. The
+`*` is replaced by the name of event, in a similar fashion to how all
+[event handlers on elements](https://html.spec.whatwg.org/multipage/webappapis.html#event-handlers-on-elements,-document-objects,-and-window-objects)
+start with `on` (e.g. `onclick`) in standard HTML. The rule of thumb is to
+simply replace `on` with `py-` and then reference the name of a Python
+function.
+
+```html title="A py-click event on an HTML button element."
+<button py-click="handle_click" id="my_button">Click me!</button>
+```
+
+```python title="The related Python function."
+from pyscript import window
+
+
+def handle_click(event):
+    """
+    Simply log the click event to the browser's console.
+    """
+    window.console.log(event)    
+```
+
+Under the hood, the [`pyscript.when`](#pyscriptwhen) decorator is used to
+enable this behaviour.
+
+!!! note
+
+    In earlier versions of PyScript, the value associated with the attribute
+    was simply evaluated by the Python interpreter. This was unsafe:
+    manipulation of the attribute's value could have resulted in the evaluation
+    of arbitrary code.
+
+    This is why we changed to the current behaviour of just supplying the name
+    of the Python function to be evaluated.
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -79,8 +79,9 @@ specification of configuration information via a _single_ `<py-config>` or
 
 ## Options
 
-There are four core options ([`interpreter`](#interpreter), [`files`](#files),
-[`packages`](#packages) and [`plugins`](#plugins)). The user is free to define
+There are five core options ([`interpreter`](#interpreter), [`files`](#files),
+[`packages`](#packages), [`plugins`](#plugins) and
+[`js_modules`](#javascript-modules).) The user is free to define
 arbitrary additional configuration options that plugins or an app may require
 for their own reasons.
 
@@ -288,7 +289,7 @@ The `plugins` option lists plugins enabled by PyScript to add extra
 functionality to the platform.
 
 Each plugin should be included on the web page, as described in the
-[plugins](#plugins_1) section below. Then the plugin's name should be listed.
+[plugins](plugins.md) section. Then the plugin's name should be listed.
 
 ```TOML title="A list of plugins in TOML"
 plugins = ["custom_plugin", "!error"]
diff --git a/docs/user-guide/features.md b/docs/user-guide/features.md
@@ -3,11 +3,11 @@
 <dl>
     <dt><em>All the web</em></dt>
     <dd>
-    <p>Pyscript gives you <a href="#the-dom">full access to the DOM</a> and all
+    <p>Pyscript gives you <a href="../dom">full access to the DOM</a> and all
     the <a href="https://developer.mozilla.org/en-US/docs/Web/API">web
     APIs implemented by your browser</a>.</p>
 
-    <p>Thanks to the <a href="#ffi">foreign
+    <p>Thanks to the <a href="../dom#ffi">foreign
     function interface</a> (FFI), Python just works with all the browser has to
     offer, including any third party JavaScript libraries that may be included
     in the page.</p>
@@ -19,10 +19,10 @@
     <dd>
     <p>PyScript brings you two Python interpreters:</p>
     <ol>
-        <li><a href="#pyodide">Pyodide</a> - the original standard
+        <li><a href="../architecture#pyodide">Pyodide</a> - the original standard
         CPython interpreter you know and love, but compiled to WebAssembly.
         </li>
-        <li><a href="#micropython">MicroPython</a> - a lean and
+        <li><a href="../architecture#micropython">MicroPython</a> - a lean and
         efficient reimplementation of Python3 that includes a comprehensive
         subset of the standard library, compiled to WebAssembly.</li>
     </ol>
@@ -38,7 +38,7 @@
     library and efficiently exposes the expressiveness of Python to the
     browser.</p>
     <p>Both Python interpreters supported by PyScript implement the
-    <a href="#ffi">same FFI</a> to bridge the gap between the worlds of Python
+    <a href="../dom#ffi">same FFI</a> to bridge the gap between the worlds of Python
     and the browser.</p>
     </dd>
 
@@ -62,15 +62,15 @@
     expensive and blocking computation can run somewhere other than the main
     application thread controlling the user interface. When such work is done
     on the main thread, the browser appears frozen; web workers ensure
-    expensive blocking computation <a href="#workers">happens elsewhere</a>.
+    expensive blocking computation <a href="../workers">happens elsewhere</a>.
     Think of workers as independent subprocesses in your web page.</dd>
 
     <dt><em>Rich and powerful plugins</em></dt>
     <dd>
     <p>PyScript has a small, efficient yet powerful core called
     <a href="https://github.com/pyscript/polyscript">PolyScript</a>. Most of
     the functionality of PyScript is actually implemented through PolyScript's
-    <a href="#plugins_1">plugin system</a>.</p>
+    <a href="../plugins">plugin system</a>.</p>
 
     <p>This approach ensures a clear separation of concerns: PolyScript
     can focus on being small, efficient and powerful, whereas the PyScript
