Review docs on troubleshooting and correcting a stale JS build

[willingc]

• Review existing section in docs on the process of checkout and build of notebook including JS
• Create a section or FAQ for Troubleshooting/Tips
  • Q: What if my Notebook's user interface doesn't look as expected?
  • A: Check if you have run npm run build prior to jupyter notebook.
  • Q: Is there a way to automate entering npm run build each time that I run new code updates
  • A:
• Revisit the docs on editing the notebook configuration.
• Add a link from the README to a Troubleshooting/Tips page in the docs
• Consider adding a more prominent note in README about npm run build with link to more details

Feedback from @fperez about stale JS in issue #708

it was trying to run the notebook itself from a git master checkout. But I forgot to run npm run build, so my JS assets were out of date. And, not having stated either in my config or at the command line the ignore_minified_js=True flag, then I was getting stale JS assets.

The behavior was thus rather confusing: at the command-line, a jupyter notebook --version call looked OK, since it reported a current version, which was indeed true. But that current version was 'half-current', if you will, since it was 'python-current', but 'javascript-old', as it was still running old JS code, from whenever I had last run a JS build.

So, the summary is, you either:

get religious about always running npm run build

or you configure your setup with the ignore_minified_js=True flag.

[minrk]

We have git hooks (in top-level git-hooks folder) that should ensure js is up-to-date on checkout/pull, so only local changes you have made since checkout will require rebuild.

Personally, I would discourage putting ignore_minified_js=True in a config file so that it's always on, since it further separates a dev environment from a real one. I do, however, have an alias

alias nbdev='jupyter notebook --NotebookApp.ignore_minified_js=True --port=9999'

so that I can turn this on when I'm debugging javascript.

[fperez]

@minrk, good points. I wasn't aware of those git hooks...

One question: the git hooks do the equivalent, if I read them correctly, of rerunning python setup.py js/css when needed. That triggers ultimately an npm run build, if I'm not mistaken.

Do you know if that's smart enough to track dependencies and only build what's needed, or is it stupid and does it do a full rebuild? Just curious...

[minrk]

@fperez it's in between. It uses a very simple check for whether js or less files changed, so it shouldn't run if only Python files or docs change. It may run slightly more often than it should, though. It's also relatively rare for there to be a PR against the notebook that's not JS, so it doesn't make a difference very often. Since our js build takes so long now, I find that I don't use the hooks any more, and only build manually because I often check out branches just to look at them, not necessarily run them.

[takluyver]

Does anyone want to tackle this for 5.0, or shall we bump it again?

[gnestor]

I've struggled with this many-a-times. Here are some thoughts:

• Pull the latest from master: git pull jupyter master
  • With git-hooks installed, this will build this JS, CSS, etc. However, git-hooks needs to be installed by the user, so we shouldn't assume that the user has them installed.
• If git-hooks are not installed, rebuild the JS and CSS: npm run build
• If actively developing: npm run build:watch which just re-runs npm run build whenever the source is modified
  • @fperez I've noticed that our bower script is smart enough to only install dependencies that have changed, and since we have removed webpack, we don't really depend on anything but bower dependencies. So, build time for me is about 3s now (vs. ~12s with webpack).
  • @fperez npm run build === python setup.py js css
• When switching between major version branches (e.g. 4.x), I believe that pip install -e . is required, correct?
• If all else fails, git clean -xfd and pip install -e . should do it

[gnestor]

I started a PR to update CONTRIBUTING.rst. It's editable, so feel free to add to it.

[takluyver]

@gnestor do you think we should do anything more on this for 5.0? Or do you want to close it or bump it to a later milestone?

[gnestor]

@willingc Would you like to take a stab at the FAQs/troubleshooting tips? I'm not sure where those should live...

@takluyver I'll bump this in the meantime.

[Thai-Morris]

@gnestor Hey, how can I help with this issue?

[gnestor]

Hi @thachmai! Thanks for offering to contribute!

If you take a look at the description:

• A: Check if you have run npm run build prior to jupyter notebook.
• Q: Is there a way to automate entering npm run build each time that I run new code updates

The answer is: npm run build:watch. While you're at it, you can add a script to the package.json for watch that just calls npm run build:watch. It is common practice to provide a npm run watch script these days 👍

• Revisit the docs on editing the notebook configuration.

I'm not sure what we need here...

• Add a link from the README to a Troubleshooting/Tips page in the docs

The troubleshooting docs are located at

notebook/CONTRIBUTING.rst

Line 76 in 5711075

Troubleshooting the Installation

[JohannaHillebrand]

Do you still need help with these issues? (I'm rather new, but would like to find a way into supporting open-source-projects)

[gnestor]

Hi @JohannaHillebrand! 👋 Thanks for reaching out.

@Thai-Morris Have you made any progress on this? If not, @JohannaHillebrand feel free to take the lead on this 👍

[jtpio]

Closing as the build process with the current state of main (which targets Notebook 7 based on JupyterLab) is now quite different to what the original issue reported.

Contributing guidelines are now in https://jupyter-notebook.readthedocs.io/en/latest/contributing.html.

To contributed to the classic notebook UI, please refer to the NBClassic documentation: https://nbclassic.readthedocs.io/en/latest/

Thanks all!