Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ The choices that the code does not explain, with the options that were rejected.
- **Marks on lines of output come from line states**: `[!code highlight]` and the state directives mark the line in the output panel with `decorateLine()`, the code that marks lines of code, so the classes, the screen reader name and the labels are the same. The build puts each marked line in a `hidden` element in the figure, and the client clones it when the line prints. A highlight uses Expressive Code's mark colours through `scb-state-mark`. The output colours meet 4.5:1 only on the code background, so a marked line takes the text colour of its label, which meets 4.5:1 on the tint. With line states off, the state directives are unknown, as on code lines, and `[!code highlight]` on an output line warns. *Rejected:* the output colours corrected for each tint (a new setting for each state and stream); `.ec-line` elements in the panel for Expressive Code's per-theme colours (client modules and components find code lines by that class); HTML strings in a data attribute (needs `innerHTML`); a `<template>` (Starlight's `<Tabs>` parses its HTML again with Sätteri, which drops the template content).
- **Scripted output takes a language, so terminal colours come from Shiki's `ansi`**: `runnable.outputLang` on the fence line, and `lang=` on an `[!output]` line for the lines after it. The user chose this over Rich markup (`[red]…[/]`): EC already renders `ansi`, and a language works for `json` or `yaml` output too. The output lines leave the code before EC highlights, so `output-highlight.ts` renders them with a second EC engine on the site's themes, then corrects each token colour to 4.5:1 on its own background, with its alpha blended in, because EC corrects syntax colours only and ANSI colours and `dim` come out unreadable on many themes. EC switches token colours with the theme only inside `.ec-line`, so the runnable plugin writes the same rules for the panel with `themedCss()`. `txt` keeps a part in its stream colour. A marked line keeps only its text, as the line above says. `\e[`, `\x1b[`, `\033[` and `\u001b[` stand for the escape character, which a fence line cannot hold, and a second backslash before one keeps it as text (`\\e[` shows `\e[`), for output such as a regular expression. Other backslashes stay as written. Real runs with `ansi` are parsed in the client (`client/shared/ansi.ts`), because their output is known only in the browser: the 16 standard colours are `codeblocksRunnable.ansi*` style settings from the theme at 4.5:1, `dim` takes the muted colour, and 256-colour and RGB colours stay as printed. Other languages do not colour a run. *Rejected:* a Rich markup parser (a port of Rich's markup, style and colour code for one use); `.ec-line` in the panel (as above); Shiki in the client for runs (far over the client budget).
- **`runnable.static` shows scripted output from the build, with no button, no live region and no `data-scb-runnable`, so no client module loads.** It is the page's own text, so it is not a decoration: search indexes it and HTML readers such as starlight-llms-txt keep it. It needs scripted output; without it the block warns and keeps its button. The user rejected `runnable.ran` as too close to `run`, and wanted no **Run again**.
- **Python runs act as `python <title> <args>`**, so that a command line tool in a block is the code of a real file. `sys.argv` is the title (else `main.py`) and `runnable.args`, split as a shell splits them; `SystemExit` prints only a message that is not a number, as CPython does; `COLUMNS` is the panel width, measured before each run. A session stops at `sys.exit()`, as the REPL does. *Rejected:* asking authors for `standalone_mode=False` and `prog_name` in Click calls (code that differs from what readers run); running on after `sys.exit()` (unlike Python); a separate attribute for the program name (the title already names the file).
- **Python runs act as `python <title> <args>`**, so that a command line tool in a block is the code of a real file. `sys.argv` is the title (else `main.py`) and `runnable.args`, split as a shell splits them; `SystemExit` prints only a message that is not a number, as CPython does; `COLUMNS` is the panel width, measured before each run; `FORCE_COLOR=1` is set when the block has `runnable.outputLang=ansi`, so Rich prints colours as in a terminal. A session stops at `sys.exit()`, as the REPL does. *Rejected:* asking authors for `standalone_mode=False` and `prog_name` in Click calls, or for `FORCE_COLOR` in a hidden line, (code that differs from what readers run); running on after `sys.exit()` (unlike Python); a separate attribute for the program name (the title already names the file).
- **No `runnable.autorun`.** Running code on page load was built and removed before release: a Python block then downloads Pyodide with every page view, and blocks on one page need a queue that races with clicked runs. `runnable.static` covers output that should show from the start.
- **`[!run]` holds hidden code that runs in place of the visible code**, so a terminal block can show `python hello.py --help` and run Python. The lines leave the code in the notation plugin, as output lines do, up to `[!run end]`, the next `[!output]` or the end. `lang=` picks the runtime. The figure carries the code in `data-scb-runnable-code`, and the run is never a REPL session. Scripted output wins over `[!run]`, with a warning. *Rejected:* `runnable.lang` on the fence line with the code in hidden lines (hidden lines are part of the copied text).
- **The output panel is a shade darker than the code, in the code font size**, by the user's choice, so the output reads as a separate part of the block. `outputBackground` darkens the code background by an amount for each theme type, which gives about the same step in light and dark themes, and every output colour (streams, labels, ANSI colours, highlighted tokens, line state tints) is corrected or tested against it. Inline code and highlighted output share one second Expressive Code engine (`renderTokens()`). *Rejected:* the terminal title bar colour (lighter than the code in some themes).
Expand Down
17 changes: 15 additions & 2 deletions docs/e2e/runnable.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ const MARKS = 10;
const OUTPUT_ONLY = 11;
const ANSI = 12;
const ANSI_RUN = 13;
const RUN_OTHER = 14;
const TITLE = 15;
const ANSI_PYTHON = 14;
const RUN_OTHER = 15;
const TITLE = 16;

test.beforeEach(async ({ page }) => {
await page.goto('./features/run-code/');
Expand Down Expand Up @@ -287,6 +288,18 @@ test('a run with runnable.outputLang=ansi shows the colours that the code prints
expect(await plain.count()).toBe(1);
});

test('a Python run with runnable.outputLang=ansi gets FORCE_COLOR, so Rich prints colours', async ({ page }) => {
once();
test.setTimeout(240_000);
const block = example(page, ANSI_PYTHON);
await block.locator('.scb-run').click();
const stdout = block.locator('.scb-run-stdout');
await expect(stdout).toHaveText('✔ Built in 2.1s', { timeout: 180_000 });
const built = stdout.getByText('✔ Built', { exact: true });
expect(await css(built, 'color')).not.toBe(await css(stdout, 'color'));
expect(await css(built, 'fontWeight')).toBe('700');
});

test('an output panel is a focusable region only while its output scrolls', async ({ page }) => {
const staticPanel = example(page, ANSI).locator('.scb-run-output');
await expect(staticPanel).toHaveAttribute('role', 'region');
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/extend/add-a-runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ interface Runtime {
load(code: string, options?: { packages?: string[] }): Promise<void>;
run(
code: string,
options: { signal: AbortSignal; session?: boolean; args?: string[]; file?: string; columns?: number },
options: { signal: AbortSignal; session?: boolean; args?: string[]; file?: string; columns?: number; color?: boolean },
): Promise<{ stdout: string; stderr: string }>;
}
```
Expand All @@ -31,7 +31,7 @@ The browser imports the module when a reader clicks **Run code** for the first t

When the block is a session with prompts, `code` is its commands and `session` is `true`. Run the commands as the language's REPL does, so that the output shows the value of each expression, as the block does.

`args` holds the words of the block's `runnable.args` attribute, and `file` the title of the block, for a runtime with command line arguments. `columns` is the width of the output panel in characters, for code that fits its output to a terminal. The Python runtime gives them to the code as `sys.argv` and the `COLUMNS` environment variable.
`args` holds the words of the block's `runnable.args` attribute, and `file` the title of the block, for a runtime with command line arguments. `columns` is the width of the output panel in characters, for code that fits its output to a terminal. `color` is true when the panel shows terminal colours, with `runnable.outputLang=ansi`. The Python runtime gives these to the code as `sys.argv`, the `COLUMNS` environment variable and `FORCE_COLOR=1`.

The `signal` of `run()` aborts when the run takes longer than `runnable.timeout`. The runtime must then stop the code and reject the promise. The plugin shows the timeout message, and calls `load()` again before the next run.

Expand Down
16 changes: 14 additions & 2 deletions docs/src/content/docs/features/run-code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ The file is the whole output, as in `runnable.output`. Directives in it, such as

`runnable.outputLang` on the fence line highlights the scripted output in a language. With `ansi`, the terminal colour codes in the output become colours, as in a terminal. Other languages, such as `json` or `yaml`, highlight as code does.

With `ansi`, the output of a real run shows its colours too. Python libraries such as Rich print colours only to a terminal, so set the `FORCE_COLOR` environment variable in the code, or in [hidden lines](/starlight-codeblocks/features/hidden-lines/).
With `ansi`, the output of a real run shows its colours too. Python libraries such as Rich print colours only to a terminal. So the Python runtime sets the `FORCE_COLOR` environment variable for a run with `ansi` output.

`lang=` on an `[!output]` line sets the language of the lines after it, up to the next `[!output]` line. For example, `[!output stderr lang=txt]` keeps an error in plain text in a block of `ansi` output. `txt` and `plaintext` keep the stream colours.

Expand Down Expand Up @@ -223,7 +223,7 @@ if __name__ == "__main__":

<Example code={cli} layout="tabs" hiddenAttributes="apiLinks=false" />

The help of a [Typer](https://typer.tiangolo.com/) app needs two packages that Pyodide does not install with Rich, so add `runnable.packages="markdown-it-py pygments"` to the fence line. For the colours of [rich-click](https://ewels.github.io/rich-click/) or Typer, add [`runnable.outputLang=ansi`](#output-in-a-language), and set `FORCE_COLOR` in a [hidden line](/starlight-codeblocks/features/hidden-lines/).
The help of a [Typer](https://typer.tiangolo.com/) app needs two packages that Pyodide does not install with Rich, so add `runnable.packages="markdown-it-py pygments"` to the fence line. For the colours of [rich-click](https://ewels.github.io/rich-click/) or Typer, add [`runnable.outputLang=ansi`](#output-in-a-language).

### An error

Expand Down Expand Up @@ -362,6 +362,18 @@ console.log(\`\${green('✔')} Built in \${bold('2.1s')}\`);

<Example code={ansiRun} layout="tabs" />

In Python, [Rich](https://rich.readthedocs.io/) prints its colours, because the runtime sets `FORCE_COLOR` for a run with `ansi` output:

export const ansiRunPython = `
\`\`\`py runnable runnable.outputLang=ansi
from rich import print

print("[bold green]✔ Built[/bold green] in 2.1s")
\`\`\`
`;

<Example code={ansiRunPython} layout="tabs" hiddenAttributes="apiLinks=false" />

### A command that runs Python

The terminal shows the command, and the button runs the Python after `[!run]`:
Expand Down
1 change: 1 addition & 0 deletions packages/starlight-codeblocks/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
- Run code: `runnable.args="<arguments>"` gives the code command line arguments. In Python, `sys.argv` holds the title of the block (else `main.py`) and the arguments, so a Click, Typer or argparse tool runs with no change to its code (#43)
- Run code: in Python, `sys.exit()` ends a run as it ends a program: with no `SystemExit` traceback, and with an exit message that is not a number on standard error. Before, `--help` in a Click command showed a traceback (#43)
- Run code: the `COLUMNS` environment variable of a Python run is the width of the output panel in characters, so help text from argparse and Rich fits the panel. Custom runtimes get `args`, `file` and `columns` in the options of `run()` (#43)
- Run code: a Python run with `runnable.outputLang=ansi` has `FORCE_COLOR=1` in its environment, so Rich, rich-click and Typer print colours with no hidden lines. Custom runtimes get `color` in the options of `run()`
- API links: a starlight-pydocs registry left over from an `astro dev` restart that removed starlight-pydocs from the config is dropped, so Python names no longer link to its old pages

## 1.4.1
Expand Down
3 changes: 2 additions & 1 deletion packages/starlight-codeblocks/src/client/runnable.ts
Original file line number Diff line number Diff line change
Expand Up @@ -100,17 +100,18 @@ async function run(figure: HTMLElement, panel: HTMLElement) {
controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
});
const timer = setTimeout(() => controller.abort(new DOMException('Timed out', 'TimeoutError')), timeout);
const ansi = figure.hasAttribute('data-scb-runnable-ansi');
try {
const options = {
signal: controller.signal,
session,
args: JSON.parse(figure.dataset.scbRunnableArgs ?? '[]'),
file: figure.dataset.scbRunnableFile,
columns: columns(panel),
color: ansi,
};
const output = await Promise.race([runtime.run(code, options), stopped]);
const parts = [];
const ansi = figure.hasAttribute('data-scb-runnable-ansi');
if (output.stdout) parts.push(stdout(output.stdout, ansi));
if (output.stderr) parts.push(error(t.error, output.stderr, ansi));
show(panel, ...(parts.length ? parts : [status(t.empty)]));
Expand Down
10 changes: 9 additions & 1 deletion packages/starlight-codeblocks/src/options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -154,10 +154,18 @@ export interface Runtime {
* `session` is true when `code` is the commands of a session with prompts, which run as a REPL runs them.
* `args` are the words of the block's `runnable.args` attribute, and `file` is the block's title.
* `columns` is the width of the output panel in characters.
* `color` is true when the panel shows terminal colours, with `runnable.outputLang=ansi`.
*/
run(
code: string,
options: { signal: AbortSignal; session?: boolean; args?: string[]; file?: string; columns?: number },
options: {
signal: AbortSignal;
session?: boolean;
args?: string[];
file?: string;
columns?: number;
color?: boolean;
},
): Promise<{ stdout: string; stderr: string }>;
}

Expand Down
27 changes: 20 additions & 7 deletions packages/starlight-codeblocks/src/runtimes/pyodide.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,18 @@ def _scb_session(src, g):
except BaseException as e:
tb = None if isinstance(e, SyntaxError) else e.__traceback__.tb_next
traceback.print_exception(e.with_traceback(tb))
async def _scb_run(src, g, session, argv, columns):
async def _scb_run(src, g, session, argv, columns, color):
sys.argv = list(argv)
if columns:
os.environ['COLUMNS'] = str(columns)
else:
os.environ.pop('COLUMNS', None)
# Rich reads COLUMNS once, for the console that it keeps.
# Rich and other libraries print colours only to a terminal, unless FORCE_COLOR is set.
if color:
os.environ['FORCE_COLOR'] = '1'
else:
os.environ.pop('FORCE_COLOR', None)
# Rich reads COLUMNS and FORCE_COLOR once, for the console that it keeps.
if 'rich' in sys.modules:
sys.modules['rich']._console = None
if session:
Expand Down Expand Up @@ -65,7 +70,7 @@ const install = async (py, names) => {
await py.loadPackage('micropip');
await py.pyimport('micropip').install(names);
};
const handle = async ({ id, url, code, session, args = [], file, columns, prepare, packages = [] }) => {
const handle = async ({ id, url, code, session, args = [], file, columns, color, prepare, packages = [] }) => {
try {
ready ??= import(url + 'pyodide.mjs')
.then((m) => m.loadPyodide({ indexURL: url }))
Expand Down Expand Up @@ -100,7 +105,7 @@ const handle = async ({ id, url, code, session, args = [], file, columns, prepar
globals.set('__name__', '__main__');
let failure;
try {
await runCode(code, globals, !!session, [file ?? 'main.py', ...args], columns);
await runCode(code, globals, !!session, [file ?? 'main.py', ...args], columns, !!color);
} catch (e) {
failure = e;
} finally {
Expand All @@ -118,7 +123,15 @@ const handle = async ({ id, url, code, session, args = [], file, columns, prepar
};`;

type Message =
| { code: string; session: boolean; args?: string[]; file?: string; columns?: number; packages: string[] }
| {
code: string;
session: boolean;
args?: string[];
file?: string;
columns?: number;
color?: boolean;
packages: string[];
}
| { prepare: string; packages: string[] };

interface Reply {
Expand Down Expand Up @@ -198,8 +211,8 @@ export function pyodide({ url = PYODIDE_URL }: { url?: string } = {}): Runtime {
wanted.set(code, packages);
await call({ prepare: code, packages });
},
run: async (code, { signal, session = false, args, file, columns }) => {
const message = { code, session, args, file, columns, packages: wanted.get(code) ?? [] };
run: async (code, { signal, session = false, args, file, columns, color }) => {
const message = { code, session, args, file, columns, color, packages: wanted.get(code) ?? [] };
const { stdout = '', stderr = '' } = await call(message, signal);
return { stdout, stderr };
},
Expand Down
Loading
Loading