search

jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
206 stars 61 forks source link

Bundle NodeJS with `mystmd` so users don't have to install it on their own #1443

Closed choldgraf closed 1 month ago

choldgraf commented 2 months ago

Our documentation asks users to install NodeJS and NPM on their own in addition to installing MyST. Most users aren't familiar with these workflows, and installing nodejs from scratch is an extra barrier to trying out MyST. We get a bit closer by telling users to install conda, but this has some weird stuff going on with Anaconda supposedly suing organizations that aren't paying them for using their default packaging channels.

Could we bundle the right NodeJS version with the mystmd package? This would reduce some install complexity for users if they didn't have to think about NodeJS at all.

Implementation ideas

I know that the sphinx-theme-builder package does this so perhaps we can learn from that.

It uses the nodeenv package to download Node into an isolated environment in the package. Here's where a lot of the nodejs logic is inside Furo

agoose77 commented 2 months ago

@choldgraf yes, and this is on my roadmap for 1.0. I need to revisit it because IIRC I don't think nodeenv uses per-platform wheels, so I want to check how robust it is

rowanc1 commented 2 months ago

This is only for the pypi/conda package right? Could easily see something that checks for node and a version and installs it if it isn't there?

It is nice that the npm version installs in less than a second on CI.

choldgraf commented 2 months ago

@rowanc1 yes this is just for the pip install of MyST. If I recall, nodeenv creates a .nodeenv directory and saves a node environment there, only for use by the package.

We could ask @pradyunsg for some pointers if he'd be willing to give them, I think he's wrestled with nodeenv to get this working for the sphinx-theme-builder

pradyunsg commented 2 months ago

if he'd be willing to give them

Always happy to share knowledge. ^.^

Could easily see something that checks for node and a version and installs it if it isn't there?

Absolutely! I didn't want to use the already-installed copy because I have limited trust that redistributors aren't meddling with NodeJS (whoops) but checking versions is something that sphinx-theme-builder does today -- although that serves as a sanity check of the version mismatches rather than a short-circuit. The short-circuit of using the system install of NodeJS there is documented here.

nodeenv basically downloads and installs from https://nodejs.org/download/release/ (https://github.com/ekalinin/nodeenv/blob/1.9.1/nodeenv.py#L1116) and has a bunch of environment variables it sets up to get things to use the downloaded copy.

I have some logic being injected in the bit linked in the issue description/first post/OP for making nicer tracebacks because nodeenv provides very little context in the errors that it raises in case of issues. You can do python -m nodeenv and it'll work just fine without all the runpy/rich.traceback shenanigans.