Update sphinx-js again and more edits (#4744)

This pulls in the newest commits of sphinx-js that can render type aliases and
interfaces into the docs. I used it to add documentation for `PackageType` and
`PackageData`. It also adds type params in the signature line of js functions,
which I'm actually not sure is that great since the signature line otherwise has
no types.

docs/requirements-doc.txt

@@ -18,4 +18,4 @@ pydantic
 micropip==0.2.2
 jinja2>=3.0
 ruamel.yaml
-sphinx-js @ git+https://github.com/pyodide/sphinx-js-fork@90055b1868851e6d88e492e7e526829da964bf82
+sphinx-js @ git+https://github.com/pyodide/sphinx-js-fork@a012f65542eb09664eec7f85b0c79cdca7e37588

docs/sphinx_pyodide/sphinx_pyodide/__init__.py

@@ -1,5 +1,7 @@
 from pathlib import Path
 
+from sphinx_js import renderers
+
 from .jsdoc import (
     patch_sphinx_js,
     ts_xref_formatter,
@@ -58,3 +60,10 @@ def setup(app):
     app.config.ts_type_xref_formatter = ts_xref_formatter
     app.config.ts_type_bold = True
     app.config.ts_sphinx_js_config = Path(__file__).parent / "sphinxJsConfig.ts"
+    renderers._SECTION_ORDER = [
+        "type_aliases",
+        "interfaces",
+        "attributes",
+        "functions",
+        "classes",
+    ]

docs/sphinx_pyodide/sphinx_pyodide/jsdoc.py

@@ -16,8 +16,8 @@ def ts_xref_formatter(_config, xref):
     from sphinx_pyodide.mdn_xrefs import JSDATA
 
     name = xref.name
-    if name == "PyodideInterface":
-        return ":ref:`PyodideInterface <js-api-pyodide>`"
+    if name == "PyodideAPI":
+        return ":ref:`PyodideAPI <js-api-pyodide>`"
     if name in JSDATA:
         return f":js:data:`{name}`"
     if name in FFI_FIELDS:

src/core/pyproxy.ts

@@ -2867,7 +2867,7 @@ export class PyBufferMethods {
    * @param type The type of the :js:attr:`~pyodide.ffi.PyBufferView.data` field
    * in the output. Should be one of: ``"i8"``, ``"u8"``, ``"u8clamped"``,
    * ``"i16"``, ``"u16"``, ``"i32"``, ``"u32"``, ``"i32"``, ``"u32"``,
-   * ``"i64"``, ``"u64"``, ``"f32"``, ``"f64``, or ``"dataview"``. This argument
+   * ``"i64"``, ``"u64"``, ``"f32"``, ``"f64"``, or ``"dataview"``. This argument
    * is optional, if absent :js:meth:`~pyodide.ffi.PyBuffer.getBuffer` will try
    * to determine the appropriate output type based on the buffer format string
    * (see :std:ref:`struct-format-strings`).
@@ -3015,23 +3015,23 @@ export interface PyDict
  *
  * .. code-block:: js
  *
- *    function multiIndexToIndex(pybuff, multiIndex){
- *       if(multindex.length !==pybuff.ndim){
- *          throw new Error("Wrong length index");
+ *     function multiIndexToIndex(pybuff, multiIndex) {
+ *       if (multindex.length !== pybuff.ndim) {
+ *         throw new Error("Wrong length index");
  *       }
  *       let idx = pybuff.offset;
- *       for(let i = 0; i < pybuff.ndim; i++){
- *          if(multiIndex[i] < 0){
- *             multiIndex[i] = pybuff.shape[i] - multiIndex[i];
- *          }
- *          if(multiIndex[i] < 0 || multiIndex[i] >= pybuff.shape[i]){
- *             throw new Error("Index out of range");
- *          }
- *          idx += multiIndex[i] * pybuff.stride[i];
+ *       for (let i = 0; i < pybuff.ndim; i++) {
+ *         if (multiIndex[i] < 0) {
+ *           multiIndex[i] = pybuff.shape[i] - multiIndex[i];
+ *         }
+ *         if (multiIndex[i] < 0 || multiIndex[i] >= pybuff.shape[i]) {
+ *           throw new Error("Index out of range");
+ *         }
+ *         idx += multiIndex[i] * pybuff.stride[i];
  *       }
  *       return idx;
- *    }
- *    console.log("entry is", pybuff.data[multiIndexToIndex(pybuff, [2, 0, -1])]);
+ *     }
+ *     console.log("entry is", pybuff.data[multiIndexToIndex(pybuff, [2, 0, -1])]);
  *
  * .. admonition:: Converting between TypedArray types
  *    :class: warning
@@ -3091,7 +3091,8 @@ export class PyBufferView {
 
   /**
    * The total number of bytes the buffer takes up. This is equal to
-   * :js:attr:`buff.data.byteLength <TypedArray.byteLength>`. See :py:attr:`memoryview.nbytes`.
+   * :js:attr:`buff.data.byteLength <TypedArray.byteLength>`. See
+   * :py:attr:`memoryview.nbytes`.
    */
   nbytes: number;
 

src/js/api.ts

@@ -40,7 +40,7 @@ API.setPyProxyToStringMethod = function (useRepr: boolean): void {
   Module.HEAP8[Module._compat_to_string_repr] = +useRepr;
 };
 
-/** @private */
+/** @hidden */
 export type NativeFS = {
   syncfs: () => Promise<void>;
 };
@@ -647,7 +647,7 @@ export class PyodideAPI {
   }
 }
 
-/** @hidetype */
+/** @hidden */
 export type PyodideInterface = typeof PyodideAPI;
 
 /** @private */

src/js/load-package.ts

@@ -103,6 +103,9 @@ API.setCdnUrl = function (url: string) {
 //
 const DEFAULT_CHANNEL = "default channel";
 
+/**
+ * @hidden
+ */
 export type PackageLoadMetadata = {
   name: string;
   normalizedName: string;
@@ -113,27 +116,25 @@ export type PackageLoadMetadata = {
   packageData: InternalPackageData;
 };
 
-/**
- * @private
- */
 export type PackageType =
   | "package"
   | "cpython_module"
   | "shared_library"
   | "static_library";
 
 // Package data inside pyodide-lock.json
-/**
- * @private
- */
-export type PackageData = {
+
+export interface PackageData {
   name: string;
   version: string;
   fileName: string;
   /** @experimental */
   packageType: PackageType;
-};
+}
 
+/**
+ * @hidden
+ */
 export type InternalPackageData = {
   name: string;
   version: string;

src/js/pyodide.ts

@@ -26,7 +26,7 @@ declare function _createPyodideModule(
 
 /**
  * See documentation for loadPyodide.
- * @private
+ * @hidden
  */
 export type ConfigType = {
   indexURL: string;

src/js/streams.ts

@@ -38,7 +38,7 @@ declare var FS: typeof Module.FS;
 
 // The type of the function we expect the user to give us. make_get_char takes
 // one of these and turns it into a GetCharType function for us.
-/** @private */
+/** @hidden */
 export type InFuncType = () =>
   | null
   | undefined