pyscript / docs Goto Github PK

See @JeffersGlass's and @leriomaggio's awesome talks about this.

We should dogfood this in our docs, and also explain how to do it in our docs.

Since we're using mkdocs, I believe the mkdocs-pyscript plugin is what we need.

Hi

Would it be possible to add some sort of search functionality in the docs website? I can understand that it can be a lot of work but it would be a nice to have feature. Especially, when trying to understand the workings of pyscript classes.

We don't cover enough the differences or reasons behind the usage of worker attribute in our code base ... we could do better by providing examples of what works on main or works on workers and why one would chose / pick one or another.

If you go to https://pyscript.net and click on documentation it'll redirect you to https://docs.pyscript.net/latest/ which renders badly because of the inaccessibility of static resources, if you then proceed to click on any of the links e.g. https://docs.pyscript.net/latest/tutorials/getting-started.html it'll show a 404 Not Found page.

At the same time if you go directly to https://docs.pyscript.net/ it'll redirect you to https://docs.pyscript.net/2023.09.1/ which works but appears to be a revamp of the docs and probably not as complete.

We currently don't have an easy to explain or reason about API story for upload and download (local physical storage) content from and to users file system ... @JeffersGlass wrote some receipt about it, but I think it's missing in our docs.

https://pyscript.github.io/docs/2024.2.1/user-guide/terminal does not explain how to close a terminal to free up space on the web page.

Use case:

• I want users to see that I have run pytest on the code before they rely on it. However, once the tests have run I would like to close the terminal so that users have more space to do their work. Alternatively, could I at least minimize the terminal?

    <script type="py" config="./pyscript.toml" terminal worker>
        import code, pytest, time
        pytest.main()  # Run all pytests and give the user a few seconds to read the results.
        time.sleep(3)  # Should we consider calling async.sleep() instead?
        print("-" * 20)  # When the pytests are complete, is it possible to close the terminal?
        # exit()  # Does not work
        # sys.exit()  # Does not work
        # If I cannot close the terminal, can I minimize it?
        # Last resort...
        code.interact()  # Convert the terminal into a Python REPL.
    </script>

While some examples feature the location of download location for specific versions, it would be great to have a list for old versions. Build artefact attached to GH releases would be enough.

It's often awkward to even mention polyscript, imagine me mentioning coincident ... well, we have a stack that enables PyScript with fundamental relevant dependencies and I think some word should be spent behind it:

• what's PyScript responsibility?
• what's Polyscript responsibility?
• what's coincident at all?

We can't go too deep into details, and each project has its own documentation, but I think a high overview of these projects behind might help solving, or pointing at, some issue or explanation here and there.

The current page makes it hard to pin-point the setup part of the documentation + we're missing details around the config so that people believe having a py-config element on the page would actually have any effect on the py-editor but these are two different worlds so we need to be explicit about it.

/cc @ntoll

In:

• https://pyscript.github.io/docs/2024.2.1/user-guide/configuration/

It says:
"However, from polyscript.js_modules import html_escaper would then only work within the context of Python code running on a worker."

Should this be: pyscript.js_modules ?

The simple clock url on the example page returns a 404 error

Speculation: The example might have been merged with the hello world example, so maybe the link can either be removed or replaced

If you got to a URL on our (new) docs that doesn't exist (like https://docs.pyscript.net/foo), you get an ugly basic 404 result:

I think we need to re-add a custom 404 page or error.html to our docs to help with this. I thought mkdocs automatically generated one, but perhaps there's something about our deployment I don't know.

There's quite a lot to unpack from this MR pyscript/pyscript#2095 and we should have proper documentation once that lands as next release.

At PyCon, we identified that having a CONTRIBUTING.md doc would be useful for new contributors.

Me and @JeffersGlass had a very lengthy conversation in Discord that started here: https://discord.com/channels/972017612454232116/972020206538997822/1250818968466362378

It's clear people using PyScript don't (know or ...) pay enough attention to the pinned version of a module concept, so that it's expected from them to be surprised when we do a release, we update our interpreters, and stuff suddenly break for everyone that didn't get the "pin your package" memo.

The issue gets bigger when packages like Bokeh require, and maybe even provide, their own CDN to make it work.

In that case, the user had Bokeh 2.4.2 pinned as <script ...> dependency on their Web page, but no pinning version whatsoever in their packages = ["bokeh"] configuration.

We don't expect neither Pyodide nor MicroPython to change behavior around grabbing whatever latest stable version of a package there is, when no versioning is provided, but definitively we should inform our users the moment they don't pin a package version, specially if there is a JS counter part to satisfy that version, stuff might break unexpectedly (and it's not our fault, or Pyodide or MicroPython fault, it's a documentation fault, imho).

IWBNI there was a mechanism detailed where I could:

• develop my pyscript code in editor of my choice
• save to github
• run workflow to:
  • send to pyscript.com and run
  • setup a github.io page or similar

There are a lot of repeated questions in Discord about the very same error over and over ... CDN issues, SharedArrayBuffer and COOP related issues, local vFS VS Server files hosted here and there ... these scenario require a dedicatewd space to me as it feels weird to need to always re-answer the same questions for people that even read the docs but couldn't figure out what's going on.

A page dedicated to what's in pyscript module feels like a must have in our docs. We do describe things by topic, we (AFAIK) don't describe things actually landing in our module or how these should be used, if these are experimental, or whatnot around our exports (disambiguating also what works in pyodide and what doesn't in micropython).

They make documentation harder to read, add no information, and can cause frustration in users. https://justsimply.dev/ I would like to remove them.

This is on the RC2 docs release.

On Chromium version 117.0.5938.92 (Official Build) snap (64-bit)
Ubuntu 22.04.1 LTS

The issue in a nutshell: users might see this error:

💀🔒 - Possible deadlock if proxy.runAsync(...args) is awaited

This comes from coincident but it's actually very poorly documented among all projects (nothing in coincident, nothing in polyscript, nothing in PyScript) so I think we should improve the current state of affairs around this possible issue that we can't actually solve but it might bother users not understanding what's wrong with the code they wrote.

https://docs.pyscript.net/2024.5.2/beginning-pyscript/#sharing-your-app

Why is it "Sharing"? Seems "Running" or "Using" is the right word.

Checklist

• I added a descriptive title
• I searched for other issues and couldn't find a solution or duplication
• I already searched in Google and didn't find any good information or help

What happened?

When I clicked the link on your guide on the Beginning PyScript webpage I see

The 'on your guide' hyperlink needs to be modified. I think on your guide route should be changed as below.

• https://docs.pyscript.net/2023.11.1.RC3/beginning-pyscript/user-guide.md -> https://docs.pyscript.net/2023.11.1.RC3/user-guide/.

What browsers are you seeing the problem on? (if applicable)

Chrome

Console info

No response

Additional Context

No response

JS Console shows mini-coi.js complaining about scope within ServiceWorker registration.

docs.pyscript.net/:1 Uncaught (in promise) DOMException: Failed to register a ServiceWorker for scope ('https://docs.pyscript.net/2023.11.1.RC3/beginning-pyscript/') with script ('https://docs.pyscript.net/2023.11.1.RC3/javascripts/mini-coi.js'): The path of the provided scope ('/2023.11.1.RC3/beginning-pyscript/') is not under the max scope allowed ('/2023.11.1.RC3/javascripts/'). Adjust the scope, move the Service Worker script, or use the Service-Worker-Allowed HTTP header to allow the scope.

I also guess (total guess actually but I think @JeffersGlass looked into it) that it may be interfering with our ability to use pyscript-mkdocs to actually make the examples interactive

After the update the documentation for previous version is gone.

Following the recommendation to pin the pyscript version this makes a delayed migration hard.

Maybe this is out of scope for the current phase, still it would be convenient.

I feel like this is a low hanging fruit that's easy to cover and explain, but users might be confused by why we offer or they would need both.

I don't know how big of a priority this is, but it feels right to me to have this documented somehow or somewhere in our pages.

On https://docs.pyscript.net/2024.5.2/developers/ under "Prepare your repository," all of the examples for how to add/manage remotes are for HTTPS.

Trying to use HTTPS with GitHub can be confusing, especially for beginners. Perhaps add examples for managing remotes via SSH?

We now have explicit support to running PyScript offline and we just need to document it. Reference here.

The URL https://pyscript.github.io/docs/2024.2.1/user-guide/first-steps locks on a particular version which is often useful.
The URL https://pyscript.github.io/docs/2024.3.1/user-guide/first-steps locks on a particular version which is often useful.

However, sometimes when documenting solutions it is helpful to point to the current docs which will change over time. In this latter case, a URL like https://pyscript.github.io/docs/stable/user-guide/first-steps (stable) can also be quite useful.

This happens with:

• https://pyodide.org/en/stable/console.html # Currently Py3.11
• https://pyodide.org/en/latest/console.html # Currently Py3.12
• https://docs.djangoproject.com/en/4.2/faq/install/#what-python-version-can-i-use-with-django # Currently Dj4.2
• https://docs.djangoproject.com/en/stable/faq/install/#what-python-version-can-i-use-with-django # Currently Dj5.0
• https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django # Currently Dj5.1

We have a flourishing community. We should highlight where they are via a community page.

Suggested first pass at content:

• Links / instructions to discord.
• @JeffersGlass's recipes blog.
• @JeffersGlass's YouTube channel.
• PyScript community call details.
• PyScript YouTube channel.
• Links to talks at community conferences (PyCons) and associated videos thereof.
• Instructions for how to add oneself to the community page!

:-)

I feel like we don't explain enough what's the need or difference between pyodide.ffi and what we offer.

This would cover also experimental_create_proxy = "auto" feature, vaguely explained or even present in our docs, but I think both create_proxy and to_js should be explained in terms of interpreters need and/or requirements.

https://docs.pyscript.net/2024.5.2/beginning-pyscript/#indexhtml

It wasn't obvious how to report an issue.

example of goodness
https://f4pga.readthedocs.io/en/latest/getting-started.html
bottom of the page is GitHub https://github.com/chipsalliance/f4pga

which isn't really "log doc issues here" but it's better than nothing. it gets me to a place where I can do something as opposed to "I want to tell someone.. oh well, I give up."

We found with contributors/sprinters at PyCon that having issue templates would be helpful here. Maybe we can steal them from the PyScript repo?

I found two links return 404 or ERR_CONNECTION_REFUSED from doc version 2024.5.2

• Web Workers > Workers click [coincident library]
  

• User guide > Use Offline > Get PyScript core
  

We talk about how to bootstrap a terminal, we don't spend much time around these facts:

• each terminal is reachable through the DOM as script.terminal attribute or as __terminal__ reference in Python
• the previous reference allows adding any extra plugin to the terminal or do more ...

I think we should talk about it in details.

https://docs.pyscript.net/2024.5.2/beginning-pyscript/#from-a-web-server

, but any static web host will do (for example github...

It doesn't include python3 -m http.server which was mentioned at the top of the page:

https://docs.pyscript.net/2024.5.2/beginning-pyscript/#an-application

If you're using your local file system
... 
python3 -m http.server

Which A) works fine and B) is my preference.

Technically the docs say run it and refresh later but for a Getting Started follow these easy steps I was expecting to be told when to run the server and browse the URL.

Explicit is better than implicit.

When going to https://docs.pyscript.net/2024.5.2/beginning-pyscript, the embedded example app is blocked.

Debian 12 (bookworm), with Firefox 115.9.1esr (64 bit, no add-ons)

Under PyScipt core from source, there is a link to https://docs.pyscript.net/developers, which results in a 404. If I click on Developer Guide in the menu, I get: https://docs.pyscript.net/2024.5.2/developers/

https://docs.pyscript.net/2024.5.2/beginning-pyscript/#indexhtml

so the <body> now looks like:
...
  <input type="text" name="english" id="english" placeholder="Type English here..." />

a bit below it says:

In the end, our HTML should look like this:
...
    <input type="text" id="english" placeholder="Type English here..." />

name="english" is missing.

We had the community call https://www.youtube.com/watch?reload=9&v=2D7Wjoj2lXc and it was clear the optional need for a config attribute or <py-config> or even <mpy-config> is not super clear in our docs.

We start the configuration section like this: https://docs.pyscript.net/2024.6.1/user-guide/configuration/

We need to tell PyScript how we want such Python environments to be configured

While true as a statement, this is a bit misleading in there to me: we don't need to tell anything to any interpreter ... unless we do.

This issue is to try brainstorming or improve that initial Configuration paragraph that sounds like a config is needed by all mean, and we already had users slightly confused about empty configs and the config meaning in general.