Skip to content

Commit fc2a528

Browse files
pauleverittpauleveritt
committed
Do a writeup of the problem and solution.
1 parent 45384c7 commit fc2a528

File tree

4 files changed

+112
-0
lines changed

4 files changed

+112
-0
lines changed

‎TODO.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
## Now
44

5+
- CDN mode
6+
7+
## Soon
8+
9+
- Start documentation for example writers
10+
- Explain that we own the `src` in `py-config`
11+
512
## Eventually
613

714
- Get nox to work with downloaded pyodide/pyscript

‎docs/developers/cdn_mode.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# CDN Mode
2+
3+
Add a way to get PyScript/Pyodide locally sometimes, but from CDN other times.
4+
5+
## Why
6+
7+
When running and testing locally, the developers (and example writers) want fast turnaround.
8+
They don't want to keep going out on a possibly-slow network -- or even no-network, if offline.
9+
In "production", though, we want people browsing the examples to get the CDN version.
10+
11+
Other times are harder to decide.
12+
GitHub Actions would like a nice speedup.
13+
But it will take some investigation to learn how to cache artifacts.
14+
15+
## When
16+
17+
There are several contexts where this decision needs to be made.
18+
19+
## Standalone Example
20+
21+
The Gallery examples are designed to allow people to preview an example's `index.html` without the app.
22+
They have a `<script>` in `<head>` pointed at `pyscript.js`.
23+
They also have a `<py-config>` in the body to point at a Pyodide runtime.
24+
25+
We encourage them to point at the locally-downloaded assets.
26+
The build step then removes those nodes from the generated output, inserting the Gallery's decision on both.
27+
28+
### Local Web App
29+
30+
Some people will pip install the PSC and go through them locally.
31+
Perhaps even hack on them.
32+
Or, contributors writing an example will want a preview.
33+
Both will fire up Starlette locally.
34+
35+
### Local Playwright
36+
37+
When running an "end-to-end" (E2E) test, you want fast turnaround.
38+
You don't want to go out on the network, repeatedly.
39+
40+
### Local/GHA Nox
41+
42+
Nox is used to run our "machinery" in isolation.
43+
We run it locally, as a last step before pushing.
44+
We might also run it locally just for automation, e.g. the reloading Sphinx server.
45+
But it also runs when GitHub Actions workflows call it.
46+
47+
In theory, you want local Nox to be exactly the same as GHA Nox.
48+
Otherwise, you aren't recreating the build environment.
49+
50+
### Production Static Website
51+
52+
The GHA generates a static website.
53+
This should be pointed at the CDN
54+
55+
## Where
56+
57+
The moral of the story: we should point at the CDN *unless* something says to point at local.
58+
There are several places we make point at assets.
59+
60+
### `pyscript.js`
61+
62+
Two locations.
63+
First, in an example's `index.html`, when it is viewed "standalone".
64+
Second, in the `example.jinja2` template's `<head>`.
65+
66+
### `gallery/examples/pyconfig.toml`
67+
68+
This is also pointed to in two locations.
69+
Again, from an example's `index.html`.
70+
Here you'll have a `<py-config src="../pyconfig.toml">` node which might include some instructions in the content.
71+
72+
## Solution
73+
74+
During local (non-CDN) use, we'll change the `<py-config>` to use `src="pyconfig.local.toml`.
75+
76+
How?
77+
We're already using BeautifulSoup to pick apart the `index.html`.
78+
Once we make the local vs. CDN decision, we can easily change the `src` attribute to point either TOML file.
79+
80+
What is the local vs. CDN criteria?
81+
We'll just look for the `src/pyscript` and `src/pyodide` directory.
82+
If they exist, then someone downloaded the assets.
83+
That's a good flag for whether to point at those directories.
84+
85+
## Actions
86+
87+
- Remove the timeout
88+
- Test/implementation that calls a `is_local` function to detect the correct mode
89+
- Test/implementation which wires that into the HTML munger
90+
- Make a `pyscript_path` which is passed into the `example.jinja2` template
91+
- E2E test which detects correct case
92+
- Revisit if `fake` and interceptor are needed

‎docs/developers/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Developers
2+
3+
Articles and notes for the implementers of the app itself.
4+
5+
```{toctree}
6+
---
7+
hidden:
8+
maxdepth: 1
9+
---
10+
11+
cdn_mode
12+
```

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ maxdepth: 1
1515
1616
contributing
1717
building/index
18+
developers/index
1819
Code of Conduct <codeofconduct>
1920
License <license>
2021
Changelog <https://github.com/pyscript/pyscript-collective/releases>

0 commit comments

Comments
 (0)