Instead of trying to convince setup.py to do what we want, the wheel
package empowers us to unpack and directly manipulate the wheel.
In particular this is important because `--skip-build` really does
not work.

First we build a native wheel. If skip_host is True, then this
"native" wheel has defective empty files as binaries, if it's False,
we build a real native wheel. If skip_host is False, then we use
pip to install our native wheel into host directory.

Then we unpack the wheel, replace the platform tag with
wasm32_emscripten, remove the non-metadata files, and copy in the
new files with the cross compiled binaries.

Of course, this is all only necessary for binary extensions.


Hopefully this will help get us towards using alternative build
backends. The one concern is that this approach depends on
implementation details of where the build backend puts the files
into the directory tree before copying them into the wheel. If
the build backend moved the linked binaries after building them,
we would be in trouble. Or worse if the build backend deleted the
files after packing them into the wheel, we'd be in trouble.

Basically, it seems clear that we can only support alternative
build backends on a case-by-case basis.

@henryiii I'm curious what your thoughts are cross compilation + arbitrary build backends.

Better package cross compilation. Instead of trying to convince setup.py to do what we want, the wheel
package empowers us to unpack and directly manipulate the wheel.
In particular this is important because `--skip-build` really does
not work.

First we build a native wheel. If skip_host is True, then this
"native" wheel has defective empty files as binaries, if it's False,
we build a real native wheel. If skip_host is False, then we use
pip to install our native wheel into host directory.

Then we unpack the wheel, replace the platform tag with
wasm32_emscripten, remove the non-metadata files, and copy in the
new files with the cross compiled binaries.

Of course, this is all only necessary for binary extensions.


Hopefully this will help get us towards using alternative build
backends. The one concern is that this approach depends on
implementation details of where the build backend puts the files
into the directory tree before copying them into the wheel. If
the build backend moved the linked binaries after building them,
we would be in trouble. Or worse if the build backend deleted the
files after packing them into the wheel, we'd be in trouble.

Basically, it seems clear that we can only support alternative
build backends on a case-by-case basis.

@henryiii I'm curious what your thoughts are cross compilation + arbitrary build backends.

# Sphinx-Pyodide

This package is a special sphinx extension for Pyodide's documentation.
The three separate files do three unrelated tasks:

## packages

Adds a custom directive which makes a table of the Pyodide packages

## lexers

Adds custom pyodide Pygments lexers that provides syntax highlighting for
Javascript with embedded Python code, and for HTML with embedded Javascript that
itself contains embedded Python.

e.g., in

```pyodide
await pyodide.loadPackage(numpy);
pyodide.runPython(`
    def f(y):
        return y + ${x}
    f(7)
`);
```

the code inside of `pyodide.runPython` is highlighted as Python, the other code
is highlighted as Javascript. Similarly with `html-pyodide`:

```html-pyodide
<div></div>
<script type="text/javascript">
console.log(pyodide.runPython(`
    import sys
    sys.version
`));
</script>
```

## jsdoc

This extends `sphinx-js` for our purposes. This contains a mix of missing
features that could ideally be upstreamed into `sphinx-js` and custom code that
can't be upstreamed.

### TsAnalyzer monkey patches

We monkey patch `TsAnalyzer._type_name` to fill in formatting of types that were
left as TODOs by `sphinx-js` (this could probably be upstreamed).

We monkey patch `TsAnalyzer._convert_node` to fix two crashes (could be
upstreamed) and to turn a destructured object argument into a list of argument docs:

```js
/**
* @param options
*/
function f({x , y } : {
    /** The x value */
    x : number,
    /** The y value */
    y : string
}){ ... }
```

should be documented like:

```
options.x (number) The x value
options.y (number) The y value
```

### `js:function`

We update the `js:function` directive to display `async` in front of async
functions.

### `PyodideAnalyzer`

We compose `TsAnalyzer` into `PyodideAnalyzer`. This prunes out private
functions, marks functions as `async` so we can display `async` in front of
them, and organizes functions into our three categories:

- `globalThis`: globaly exposed functions
- `pyodide`: pyodide APIs
- `PyProxy`: `PyProxy` APIs

It also classifies them into three types: function, class, or attribute so we
can separate them out in the summary.

### js-autodoc

`sphinx-js` doesn't include full recursive layout features by default. This adds
a `js-doc-summary` directive and a `js-doc-content` directive. `js-doc-summary`
makes a summary table for any category (`globalThis`, `pyodide` or `PyProxy`)
and `js-doc-content` formats the main documentation content. These are used in
`js-api.md`. A lot of this code is similar to the `autosummary` package, but
there are enough differences that it was easier to copy the code in.

## autodoc_submodules

This makes autodoc recursively document submodules, mixed in with the top level
docs. For instance, `pyfetch` is defined in `pyodide.html`. This adds an entry
called `http.pyfetch` to the list of documented APIs for `pyodide`.

# Sphinx-Pyodide

This package is a special sphinx extension for Pyodide's documentation.
The three separate files do three unrelated tasks:

## packages

Adds a custom directive which makes a table of the Pyodide packages

## lexers

Adds custom pyodide Pygments lexers that provides syntax highlighting for
Javascript with embedded Python code, and for HTML with embedded Javascript that
itself contains embedded Python.

e.g., in

```pyodide
await pyodide.loadPackage(numpy);
pyodide.runPython(`
    def f(y):
        return y + ${x}
    f(7)
`);
```

the code inside of `pyodide.runPython` is highlighted as Python, the other code
is highlighted as Javascript. Similarly with `html-pyodide`:

```html-pyodide
<div></div>
<script type="text/javascript">
console.log(pyodide.runPython(`
    import sys
    sys.version
`));
</script>
```

## jsdoc

This extends `sphinx-js` for our purposes. This contains a mix of missing
features that could ideally be upstreamed into `sphinx-js` and custom code that
can't be upstreamed.

### TsAnalyzer monkey patches

We monkey patch `TsAnalyzer._type_name` to fill in formatting of types that were
left as TODOs by `sphinx-js` (this could probably be upstreamed).

We monkey patch `TsAnalyzer._convert_node` to fix two crashes (could be
upstreamed) and to turn a destructured object argument into a list of argument docs:

```js
/**
* @param options
*/
function f({x , y } : {
    /** The x value */
    x : number,
    /** The y value */
    y : string
}){ ... }
```

should be documented like:

```
options.x (number) The x value
options.y (number) The y value
```

### `js:function`

We update the `js:function` directive to display `async` in front of async
functions.

### `PyodideAnalyzer`

We compose `TsAnalyzer` into `PyodideAnalyzer`. This prunes out private
functions, marks functions as `async` so we can display `async` in front of
them, and organizes functions into our three categories:

- `globalThis`: globaly exposed functions
- `pyodide`: pyodide APIs
- `PyProxy`: `PyProxy` APIs

It also classifies them into three types: function, class, or attribute so we
can separate them out in the summary.

### js-autodoc

`sphinx-js` doesn't include full recursive layout features by default. This adds
a `js-doc-summary` directive and a `js-doc-content` directive. `js-doc-summary`
makes a summary table for any category (`globalThis`, `pyodide` or `PyProxy`)
and `js-doc-content` formats the main documentation content. These are used in
`js-api.md`. A lot of this code is similar to the `autosummary` package, but
there are enough differences that it was easier to copy the code in.

## autodoc_submodules

This makes autodoc recursively document submodules, mixed in with the top level
docs. For instance, `pyfetch` is defined in `pyodide.html`. This adds an entry
called `http.pyfetch` to the list of documented APIs for `pyodide`.
