help menu in jupyter notebook

[Denis]

At some point the help menu in jupyter notebooks started pointing to doc.sagemath.org instead of the locally built documentation. I wouldn't mind having a configuration option not to build the documentation, in which case, of course, this would be expected. However, because the documentation is still built by default, it looks more like a bug than a feature. Any thoughts?

Denis

[Kwankyu Lee]

On Wednesday, April 10, 2024 at 1:30:21 AM UTC+9 Denis wrote:

At some point the help menu in jupyter notebooks started pointing to doc.sagemath.org instead of the locally built documentation. I wouldn't mind having a configuration option not to build the documentation, in which case, of course, this would be expected. However, because the documentation is still built by default, it looks more like a bug than a feature. Any thoughts?

That was done because jupyterlab help menu does not support loading local documentation. 

See https://github.com/sagemath/sage/pull/36246

Any idea to improve the situation? 

[Denis]

Only to put a note in the installation instructions somewhere, along the lines:

If the URL in your browser reads /foo/bar/notebooks/whatever.ipynb, then /foo/bar/kernelspecs/sagemath/doc/html/en/index.html will take you to the local documentation.

I have bookmarked a few such links, which is good enough for me, the only problem was figuring out the url.

Also maybe one could point out how to skip building the documentation.

Denis

[Marc Culler]

Another drawback of linking to online documentation is that the online documentation is always for the current release version of Sage, not the Sage that the user happens to be running,.

I have a suggestion to improve the situation, which is to do what the Sage_macOS app does.

The app provides access to a local copy of the documentation stored inside the application bundle.  The files are reorganized slightly to remove duplication and then compressed with gzip.  The app views the files using cocoserver, which provides a slightly modfiied subclass of Python's ThreadingHTTPServer.  The behavior of that server is modified so that it adds a gzip header to any file named *.gz.  The browser automatically decompresses gzipped files served with such a header.  ("Coco" stands for "compressed content".)

Compressing the documentation reduces the size (of the English documentation) from about 600 GB to about 100 GB.

The app also makes some small changes to the files __main__.py and kernel.py in sage/repl/ipython_kernel to make jupyter add options to  its Help menu for viewing the Sage documentation.

- Marc

[Nils Bruin]

On Friday 26 April 2024 at 06:53:28 UTC-7 marc....@gmail.com wrote:

I have a suggestion to improve the situation, which is to do what the Sage_macOS app does.

The app provides access to a local copy of the documentation stored inside the application bundle.  The files are reorganized slightly to remove duplication and then compressed with gzip.  The app views the files using cocoserver, which provides a slightly modfiied subclass of Python's ThreadingHTTPServer.  The behavior of that server is modified so that it adds a gzip header to any file named *.gz.  The browser automatically decompresses gzipped files served with such a header.  ("Coco" stands for "compressed content".)

Yes, I was thinking in that direction too. Is there perhaps already a jupyter server extension that can serve files in a local directory? I bet we can instruct jupyterlab to point at a "localhost" url rather than at "doc.sagemath.org"

 

Compressing the documentation reduces the size (of the English documentation) from about 600 GB to about 100 GB.

You meant MB probably?

 

[Marc Culler]

Yes, I meant MB.  Thanks.

There are other issues with viewing local documentation files in a browser.  On Ubuntu, Chrome and Firefox are packaged as snaps.  A snap is not allowed to read a file:// url which is not in the user's home directory.  As long as sage is installed in the user's home directory this is not an issue.  But if the documentation is elsewhere then Firefox and Chrome will refuse to show it.  Using the cocoserver works around this because it is allowed to use a url with the loopback interface as the host address.  (I think it is safer to use 127.0.0.1 instead of localhost because, in principle, a rogue DNS server would be able to provide any IP address as an A record for localhost).  I don't know if there is a jupyter extension that provides access to local files on the loopback interface.

- Marc

--
You received this message because you are subscribed to a topic in the Google Groups "sage-devel" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sage-devel/kzSWB8ps7VA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sage-devel+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/4e33bc5d-ba8e-419d-92a3-87977765ad86n%40googlegroups.com.

[Nils Bruin]

On Friday 26 April 2024 at 12:29:14 UTC-7 marc....@gmail.com wrote:

There are other issues with viewing local documentation files in a browser.  On Ubuntu, Chrome and Firefox are packaged as snaps.  A snap is not allowed to read a file:// url which is not in the user's home directory.  As long as sage is installed in the user's home directory this is not an issue.  But if the documentation is elsewhere then Firefox and Chrome will refuse to show it.  Using the cocoserver works around this because it is allowed to use a url with the loopback interface as the host address.  (I think it is safer to use 127.0.0.1 instead of localhost because, in principle, a rogue DNS server would be able to provide any IP address as an A record for localhost). 

The most flexible would be to serve it from would be whatever address the jupyter server is serving on. That's why it might be easier to get this to behave properly as a jupyter extension, because it could even serve it on the same port in that case. I guess the OSX app has hardcoded that it serves on 127.0.0.1 then? How do you work around port availability there? Does coco listen on a separate port from the jupyter server?

[Marc Culler]

The jupyter server operates on the loopback interface which has IP address 127.0.0.1 and IP name localhost.  The cocoserver uses that same interface.  Jupyter tries to get port 8888 and if that is busy it hunts for a nearby port that is not in use.   The cocoserver uses an arbitrary system-assigned available port in the public range (above 1000).

I don't see what difference the choice of port makes to a user.  It is not possible to guarantee that the same port will always be used, since ports are assigned on a first-come first-served basis.  Consequently it is not possible to "bookmark" the address of either a jupyter server or a cocoserver.  The port should be viewed as arbitrary and unpredictable.  The address is always 127.0.0.1 in either case, by necessity.

- Marc

[Nils Bruin]

On Friday 26 April 2024 at 15:44:22 UTC-7 marc....@gmail.com wrote:

I don't see what difference the choice of port makes to a user.  It is not possible to guarantee that the same port will always be used, since ports are assigned on a first-come first-served basis.  Consequently it is not possible to "bookmark" the address of either a jupyter server or a cocoserver.  The port should be viewed as arbitrary and unpredictable.  The address is always 127.0.0.1 in either case, by necessity.

The port number that jupyter tries to use is configurable and there can be reasons why you'd want to care about it. For instance, if you have a beefy linux server that students in various locations want to use from windows workstations. Ideally you'd run jupyterhub on it, but it's a complete headache to figure out authentication and file system access and probably impossible to find sysadmins capable and willing to make that setup secure.

Instead, one could just assign a port number to each individual so that they can set up a script to start their jupyter server on the right port on localhost. They then just need to learn to use ssh (via PuTTY, for instance) to tunnel the particular port from their desktop to the server and then they can point the browser *on their own machine* to the right address. It gets around the problem of getting people to install jupyter on a windows box and it shows them an environment in which they could graduate to useful work on the server themselves. And mainly, it gets around the very real problem of getting a JupyterHub server set up. The price you pay, of course, is that the port number is now very well-defined and actually quite important. In that setup, it would be nice if the documentation were served through the web server that jupyter is already running, because that's the only port that's tunnelled. Or if the documentation just lives on the internet; that's fine too (because if one weren't in an internet-facing environment, setting up JupyterHub would at least be less problematic from a security point of view).

So, yes, if you're really just running it locally, the port number isn't so important, but if any port forwarding comes into play, it becomes very important to know the port number!

[Marc Culler]

Yes, I was only talking about really just running Sage locally.

- Marc.

[Kwankyu Lee]

The app provides access to a local copy of the documentation stored inside the application bundle.  The files are reorganized slightly to remove duplication and then compressed with gzip.  The app views the files using cocoserver, which provides a slightly modfiied subclass of Python's ThreadingHTTPServer.  The behavior of that server is modified so that it adds a gzip header to any file named *.gz.  The browser automatically decompresses gzipped files served with such a header.  ("Coco" stands for "compressed content".)

This motivates me to open #37878.

 

[Kwankyu Lee]

On Saturday, April 27, 2024 at 2:30:00 PM UTC+9 Kwankyu Lee wrote:

The app provides access to a local copy of the documentation stored inside the application bundle.  The files are reorganized slightly to remove duplication and then compressed with gzip.  The app views the files using cocoserver, which provides a slightly modfiied subclass of Python's ThreadingHTTPServer.  The behavior of that server is modified so that it adds a gzip header to any file named *.gz.  The browser automatically decompresses gzipped files served with such a header.  ("Coco" stands for "compressed content".)

This motivates me to open #37878.

Exactly, https://github.com/sagemath/sage/pull/37878