Document better package specifics in Pyodide

[rth]

When users load a package/module in WASM VM they expect it to behave strictly identical to how it works with standard Python build.

While among packages that could be used, there are,

1. those that work perfectly (e.g. re)
2. those that mostly work, possibly with a few patches and with some known issues that could be resolved in time (e.g; numpy, scipy)
3. those that do not work and will never work (e.g. multiprocessing, sockets)
4. those that could work, with some part rewritten with Web APId (e.g. matplotlib with our custom backend, requests https://github.com/pyodide/pyodide/pull/1956)

In general, I think we should better document for each built package what would work and what wouldn't. If we go in the direction of https://github.com/pyodide/pyodide/issues/977 it could be for instance a HTML page per page with some description of what is expected to work and what doesn't. This page could also indicate how much of the original test suite passes.

All of this information should be somehow indicated in meta.yaml or possibly a separate markdown file in the package folder.

[ryanking13]

I definitely agree that we need more documentation for the known issues and limitations. Maybe a new documentation page such as Loading Packages > Known Issues / Limitations would be a good start point?

All of this information should be somehow indicated in meta.yaml or possibly a separate markdown file in the package folder.

I'm not sure these are necessary if we add all information in the documentation.

[bollwyvl]

Some more voices in the choir: https://github.com/jupyterlite/jupyterlite/issues/199

A solution we had been thinking about at the UI level: a general purpose message handler which can watch for specific strings (e.g. the pandas one about lzma) for which we can ship markdown messages to display, and then offer to hide forever.

As documentation technique, potentially moving this content out of the repo:

• a short-key wiki namespace as a place to land, e.g. https://github.com/hadolint/hadolint/wiki/DL3000
  • gh wikis are great, being repos under the hood
• a dedicated repository of issues hooked up to https://github.com/utterance/utterances
  • less good for code, but already have such strong tooling/SEO/backlinking features

However they are initially captured, being able to ship them for consumption offline is very useful!