Document {exec} micropython.

docs/demo/html.md

@@ -13,9 +13,10 @@ scripts:
 
 ## Inline document
 
-The {rst:dir}`{exec} html <exec>` directive allows displaying a complete HTML
-document as an `<iframe>`. The `<iframe>` defaults to a 16/9 aspect ratio, but
-its size can be adjusted with {rst:dir}`:output-style: <exec:output-style>`.
+The [`{exec} html`](../reference/exec.md#html) directive allows displaying a
+complete HTML document as an `<iframe>`. The `<iframe>` defaults to a 16/9
+aspect ratio, but its size can be adjusted with
+{rst:dir}`:output-style: <exec:output-style>`.
 
 ```{exec} html
 :when: load
@@ -43,8 +44,8 @@ document.addEventListener('DOMContentLoaded', () => {
 ### Partial content
 
 Browsers are smart enough to render `<iframe>` tags with partial content
-correctly. So an {rst:dir}`{exec} html <exec>` block can contain an HTML
-snippet only, and optionally styles (with a `<style>` element):
+correctly. So an [`{exec} html`](../reference/exec.md#html) block can specify
+just an HTML snippet, and optionally styles (with a `<style>` element):
 
 ```{exec} html
 :when: load

docs/demo/micropython.md

@@ -3,13 +3,8 @@
 
 # MicroPython
 
-```{admonition} Work-in-progress
-:class: warning
-This functionality is in development and unstable. Please do not use yet.
-```
-
-The {rst:dir}`{exec} micropython <exec>` directive allows uploading and
-executing Python code on an embedded system running
+The [`{exec} micropython`](../reference/exec.md#micropython) directive allows
+uploading and executing Python code on an embedded system running
 [MicroPython](https://micropython.org).
 
 ```{defaults} exec
@@ -25,7 +20,7 @@ name = input("What's your name? ")
 print("Hello, %s!" % name)
 ```
 
-## BBC micro:bit
+## BBC micro:bit V2
 
 ```{exec} micropython
 from microbit import *

docs/demo/python.md

@@ -11,8 +11,8 @@ exec:
     packages: [sqlite3]
 ```
 
-The {rst:dir}`{exec} python <exec>` directive allows executing Python code
-directly in the browser.
+The [`{exec} python`](../reference/exec.md#python) directive allows executing
+Python code in the browser.
 
 ```{exec} python
 :when: load
@@ -25,9 +25,9 @@ print(f"{platform.python_implementation()}"
 
 ## Module setup
 
-Module setup code can be defined as a named {rst:dir}`{exec} python <exec>`
-block, to be referenced in the {rst:dir}`:after: <exec:after>` option of other
-blocks.
+Module setup code can be defined as a named
+[`{exec} python`](../reference/exec.md#python) block, to be referenced in the
+{rst:dir}`:after: <exec:after>` option of other blocks.
 
 ```{exec} python
 :name: python-setup
@@ -49,10 +49,10 @@ def factorial(n):
 
 ### Terminal
 
-The terminal output generated by an {rst:dir}`{exec} python <exec>` block via
-{py:obj}`sys.stdout` and {py:obj}`sys.stderr` (and therefore, via
-{py:func}`print`) is displayed in an output block. Output to
-{py:obj}`sys.stderr` is colored.
+The terminal output generated by an
+[`{exec} python`](../reference/exec.md#python) block via {py:obj}`sys.stdout`
+and {py:obj}`sys.stderr` (and therefore, via {py:func}`print`) is displayed in
+an output block. Output to {py:obj}`sys.stderr` is colored.
 
 ```{exec} python
 :after: python-setup
@@ -220,8 +220,9 @@ print(f"The factorial of {n} is {fact}")
 
 ## Exceptions
 
-Exceptions that propagate out of the {rst:dir}`{exec} python <exec>` block are
-displayed as a traceback on {py:obj}`sys.stderr`.
+Exceptions that propagate out of the
+[`{exec} python`](../reference/exec.md#python) block are displayed as a
+traceback on {py:obj}`sys.stderr`.
 
 ```{exec} python
 :after: python-setup
@@ -239,11 +240,11 @@ outer()
 
 ## Concurrency
 
-All {rst:dir}`{exec} python <exec>` blocks on a page are executed in a shared,
-single-threaded interpreter. Therefore, only one block can run at any given
-time. Nevertheless, concurrent execution is possible through `async` coroutines.
-The {py:mod}`asyncio` module provides a lot of functionality related to `async`
-concurrency.
+All [`{exec} python`](../reference/exec.md#python) blocks on a page are executed
+in a shared, single-threaded interpreter. Therefore, only one block can run at
+any given time. Nevertheless, concurrent execution is possible through `async`
+coroutines. The {py:mod}`asyncio` module provides a lot of functionality related
+to `async` concurrency.
 
 ```{exec} python
 import asyncio

docs/demo/sql.md

@@ -3,8 +3,8 @@
 
 # SQL
 
-The {rst:dir}`{exec} sql <exec>` directive allows executing SQL directly in the
-browser. Each block is executed in a new, empty database.
+The [`{exec} sql`](../reference/exec.md#sql) directive allows executing SQL
+in the browser. Each block is executed in a new, empty database.
 
 ```{exec} sql
 :when: load
@@ -14,8 +14,9 @@ select concat('SQLite ', sqlite_version()) as Database;
 
 ## Database definition
 
-A database can be defined as a named {rst:dir}`{exec} sql <exec>` block, to be
-referenced in the {rst:dir}`:after: <exec:after>` option of other blocks.
+A database can be defined as a named [`{exec} sql`](../reference/exec.md#sql)
+block, to be referenced in the {rst:dir}`:after: <exec:after>` option of other
+blocks.
 
 ```{exec} sql
 :name: sql_countries
@@ -45,9 +46,9 @@ insert into countries values
 ## Queries
 
 The results of the **first** `select` statement in each
-{rst:dir}`{exec} sql <exec>` block of the {rst:dir}`:after: <exec:after>`
-and {rst:dir}`:then: <exec:then>` [sequence](../reference/exec.md#sequencing)
-are displayed as tables.
+[`{exec} sql`](../reference/exec.md#sql) block of the
+{rst:dir}`:after: <exec:after>` and {rst:dir}`:then: <exec:then>`
+[sequence](../reference/exec.md#sequencing) are displayed as tables.
 
 ```{exec} sql
 :editor:

docs/reference/exec.md

@@ -164,23 +164,64 @@ select * from people;
 
 ### HTML
 
-HTML code execution displays a complete HTML document as an `<iframe>`, with
-limited browsing functionality.
+The {rst:dir}`{exec} html <exec>` runner displays a complete HTML document as an
+`<iframe>`, with limited browsing functionality.
 
 ### MicroPython
 
-This runner connects to an embedded system running
-[MicroPython](https://micropython.org). The code is run from RAM and is
-therefore transient. It can also be written to the file `main.py` in flash
-memory, so that it is run at boot-time.
+The {rst:dir}`{exec} micropython <exec>` runner connects to an embedded system
+running [MicroPython](https://micropython.org). The code can either be run from
+RAM (transient, programs disappear on reset) or be written to the file `main.py`
+in flash memory (permanent, runs at boot-time).
+
+```{admonition} Note
+:class: note
+The `micropython` runner only works on devices supporting the
+[WebSerial API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API).
+Currently, this limits the use to
+[Chromium-based browsers](https://en.wikipedia.org/wiki/Chromium_(web_browser)#Browsers_based_on_Chromium)
+(e.g. Chrome, Edge, Brave).
+```
+
+The target device must already be programmed with a MicroPython firmware. The
+procedure depends on the target device type.
+
+- **BBC micro:bit V2:** Download the `.hex` file for the latest
+  [release](https://github.com/microbit-foundation/micropython-microbit-v2/releases).
+  Connect the target and mount its filesystem, then copy the file to it.
+- **Raspberry Pi Pico:** Follow the
+  [documentation](https://www.raspberrypi.com/documentation/microcontrollers/micropython.html#drag-and-drop-micropython)
+  to download the appropriate firmware file and program the device.
+
+To enable connecting to a target device, it must first be **paired with the
+browser**. Connect the target via USB, select
+"<span class="tdoc-icon fa-plug"></span>&nbsp;Connect" in the "Tools" menu
+(<button class="tdoc fa-screwdriver-wrench"></button>), and select the device
+in the list. This needs to be done only once; once a device is paired, it will
+be connected automatically when the page loads, unless multiple paired devices
+are available.
+
+To **run a program from RAM**, click the "Run" button
+(<button class="tdoc fa-play"></button>). Text input can be sent to the target
+via the input field, and the program can be interrupted with the "Stop" button
+(<button class="tdoc fa-stop"></button>). When the program terminates, the
+target returns to the
+[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) and
+accepts further commands.
+
+To **write a program permanently to a target's flash memory**, select
+"<span class="tdoc-icon fa-file-arrow-up"></span>&nbsp;Write&nbsp;to&nbsp;<code>main.py</code>"
+in the "Tools" menu. The program can be removed again with
+"<span class="tdoc-icon fa-trash"></span>&nbsp;Remove&nbsp;<code>main.py</code>".
 
 ### Python
 
-Python code execution is based on [Pyodide](https://pyodide.org/) and
+The {rst:dir}`{exec} python <exec>` runner executes code through
+[Pyodide](https://pyodide.org/) and
 [Polyscript](https://pyscript.github.io/polyscript/). All Python blocks on a
 page are executed in a shared, single-threaded interpreter.
 
-Pyodide can be configured via the `exec:python` {rst:dir}`metadata`. This
+Pyodide can be configured via the `exec:python:` {rst:dir}`metadata`. This
 enables the following functionality:
 
 - **[Copy files](https://docs.pyscript.net/latest/user-guide/configuration/#files)
@@ -206,5 +247,6 @@ exec:
 
 ### SQL
 
-SQL code execution uses a WebAssembly build of [SQLite](https://sqlite.org/).
-Each block execution is performed against a new, empty database.
+The {rst:dir}`{exec} sql <exec>` runner uses a WebAssembly build of
+[SQLite](https://sqlite.org/). Each block execution is performed against a new,
+empty database.

docs/reference/python-libs.md

@@ -4,7 +4,7 @@
 # Python libraries
 
 The modules described below are packaged into a library and made available to
-Python code executed through the {rst:dir}`{exec} python <exec>` directive.
+Python code executed through the [`{exec} python`](exec.md#python) directive.
 Additionally, all files in the directory `_python` (next to `conf.py`) are also
 included recursively in the library.
 
@@ -13,9 +13,9 @@ included recursively in the library.
 ````{py:module} tdoc.core
 This module
 ([source](https://github.com/t-doc-org/common/blob/main/tdoc/common/python/core.py))
-provides basic functionality for {rst:dir}`{exec} python <exec>` blocks. It
+provides basic functionality for [`{exec} python`](exec.md#python) blocks. It
 doesn't need to be imported explicitly: all its public symbols are available in
-the global scope of  {rst:dir}`{exec} python <exec>` blocks.
+the global scope of  [`{exec} python`](exec.md#python) blocks.
 ````
 
 ```{py:function} new_id() -> str

docs/release-notes.md

@@ -18,7 +18,8 @@
 (release-0-34)=
 ## 0.34 *(2025-02-02)*
 
-- Enabled loading packages for [`{exec} python`](/demo/python.md) blocks.
+- Enabled loading packages for [`{exec} python`](/reference/exec.md#python)
+  blocks.
   - Bundled the `micropip`, `packaging` and `sqlite3` packages.
 - Enabled calling `async` functions synchronously on Chrome-based browsers.
 - Added {py:func}`tdoc.core.input`.
@@ -114,7 +115,7 @@
 ## 0.19 *(2024-11-17)*
 
 - Fixed the un-collapsing of admonitions through click events.
-- Fixed the full-screen mode of [`{exec} html`](/demo/html.md).
+- Fixed the full-screen mode of [`{exec} html`](/reference/exec.md#html).
 
 (release-0-18)=
 ## 0.18 *(2024-11-14)*
@@ -133,7 +134,7 @@
 (release-0-16)=
 ## 0.16 *(2024-11-03)*
 
-- Added support for [`{exec} html`](/demo/html.md).
+- Added support for [`{exec} html`](/reference/exec.md#html).
 - Added support for styling editors and output blocks with
   {rst:dir}`{exec} :style: <exec:style>` and
   {rst:dir}`{exec} :output-style: <exec:output-style>`.
@@ -144,10 +145,10 @@
 ## 0.15 *(2024-10-19)*
 
 - Added a mechanism to render arbitrary HTML from
-  [`{exec} python`](/demo/python.md) blocks.
+  [`{exec} python`](/reference/exec.md#python) blocks.
 - Added a Python module to create SVG images.
-- Added automatic focusing of [`{exec} python`](/demo/python.md) text input
-  elements.
+- Added automatic focusing of [`{exec} python`](/reference/exec.md#python) text
+  input elements.
 - Fixed the positioning of the "Remove" button on scrollable tables.
 
 (release-0-14)=
@@ -165,12 +166,13 @@
 (release-0-12)=
 ## 0.12 *(2024-09-28)*
 
-- Added user input functionality for [`{exec} python`](/demo/python.md) blocks.
+- Added user input functionality for
+  [`{exec} python`](/reference/exec.md#python) blocks.
 
 (release-0-11)=
 ## 0.11 *(2024-09-27)*
 
-- [`{exec} python`](/demo/python.md) now works when offline.
+- [`{exec} python`](/reference/exec.md#python) now works when offline.
 - Fixed an issue that prevented entering the character `/` in editors.
 - Disabled the search shortcut, as it can interfere with editors.
 - Made the workaround for missing `SharedArrayBuffer` configurable.
@@ -182,7 +184,7 @@
 (release-0-10)=
 ## 0.10 *(2024-09-21)*
 
-- Added initial support for [`{exec} python`](/demo/python.md).
+- Added initial support for [`{exec} python`](/reference/exec.md#python).
   - Currently, Python code execution only works when online.
 - Made the automatic page reloading more reactive.
 - Made pages cross-origin isolated even if the server doesn't set the
@@ -219,8 +221,9 @@
 
 - Added on-click execution of {rst:dir}`exec` blocks.
 - Added support for dependencies with {rst:dir}`{exec} :after: <exec:after>`.
-- Added proper rendering of SQL errors in [`{exec} sql`](/demo/sql.md).
-- Fixed the handling of `NULL` values in [`{exec} sql`](/demo/sql.md).
+- Added proper rendering of SQL errors in
+  [`{exec} sql`](/reference/exec.md#sql).
+- Fixed the handling of `NULL` values in [`{exec} sql`](/reference/exec.md#sql).
 
 (release-0-4)=
 ## 0.4 *(2024-08-22)*

tdoc/common/static/tdoc/exec-micropython.js

@@ -33,7 +33,7 @@ class MicroPythonExecutor extends Executor {
     toolsControl() {
         const ctrl = element(`
 <div class="dropstart">\
-<button class="fa-screwdriver-wrench tdoc-tools" title="Tools"\
+<button class="tdoc fa-screwdriver-wrench" title="Tools"\
  data-bs-toggle="dropdown" data-bs-offset="-7,4"></button>\
 <ul class="dropdown-menu"></ul>\
 </div>`);
@@ -55,7 +55,7 @@ class MicroPythonExecutor extends Executor {
     menuItem(icon, text, cls, onClick) {
         const it = element(`\
 <li><a class="dropdown-item${cls}">\
-<span class="btn__icon-container tdoc-icon fa-${icon}"></span>\
+<span class="btn__icon-container tdoc fa-${icon}"></span>\
 <span class="btn__text-container">${text}</span>\
 </a></li>`);
         it.querySelector('a').addEventListener('click', onClick);