Skip to content

docs: Update packages and config - #424

Open
kadler wants to merge 1 commit into
masterfrom
doc-package-updates
Open

kadler wants to merge 1 commit into
masterfrom
doc-package-updates

Conversation

@kadler

@kadler kadler commented Sep 14, 2026

Copy link
Copy Markdown
Member
  • Update readthedocs to use Ubuntu 26.04, Python 3.13, and Node 26
  • Use uv to keep doc packages in sync
  • Update doc packages

@kadler
kadler requested a review from abmusse September 14, 2026 17:46
@kadler
kadler force-pushed the doc-package-updates branch 2 times, most recently from cd6a31b to 5dcc4c4 Compare September 14, 2026 17:51
@abmusse

abmusse commented Sep 14, 2026

Copy link
Copy Markdown
Member

@kadler

Looks like there was error with building the docs:

https://app.readthedocs.org/projects/nodejs-itoolkit/builds/34554133/

@kadler

kadler commented Sep 15, 2026

Copy link
Copy Markdown
Member Author

It appears that this is an issue with the asdf version manager that RTD uses:

/home/docs/.asdf/shims/jsdoc:2
# asdf-plugin: nodejs 26.4.0
^
SyntaxError: Invalid or unexpected token

It adds a comment to the jsdoc script shim but Node.js only supports # comments in the first line for the shebang line. Looks like the same issue as asdf-vm/asdf-nodejs#367

Here's how sphinx-js calls jsdoc: https://github.com/pyodide/sphinx-js/blob/master/sphinx_js/jsdoc.py#L280-L285 Looks like it's calling it with node path/to/jsdoc, however I don't think that matters because I can recreate this problem either way going back to Node 14:

-bash-5.2$ cat ./jsdoc-test
#!/usr/bin/env node
# asdf-plugin: nodejs 26.4.0

console.log('hi!');
-bash-5.2$ ./jsdoc-test
/QOpenSys/home/kadler/jsdoc-test:2
# asdf-plugin: nodejs 26.4.0
^

SyntaxError: Invalid or unexpected token
    at wrapSafe (internal/modules/cjs/loader.js:1029:16)
    at Module._compile (internal/modules/cjs/loader.js:1078:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1143:10)
    at Module.load (internal/modules/cjs/loader.js:979:32)
    at Function.Module._load (internal/modules/cjs/loader.js:819:12)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12)
    at internal/main/run_main_module.js:17:47

Node.js v18.20.8

@kadler

kadler commented Sep 15, 2026

Copy link
Copy Markdown
Member Author

Ok, looks like the way asdf shims it, it creates it as a bash script: https://github.com/asdf-vm/asdf/blob/master/internal/shims/shims.go#L454 So sphinx-js is trying to call this bash script as if it was JS. Unfortunately sphinx-js doesn't seem to have a bypass for this, so I'm going to try creating a JS script for it to use which calls the bash script.

- Update readthedocs to use Ubuntu 26.04, Python 3.13, and Node 26
- Use uv to keep doc packages in sync
- Update doc packages
- Add jsdoc wrapper script to work around pyodide/sphinx-js#316
@kadler
kadler force-pushed the doc-package-updates branch from 89739f7 to 656d3e3 Compare September 15, 2026 04:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants