Repository: sagemath/sage

Issue:
Run doc server along with jupyter server
<div id="comment:0"></div>

Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface, although they work fine in jupyter notebook interface.

Jupyterlab loads local files (sage documentation files) in `iframe` tag. This is problematic and it seems hopeless to make this work. A proper way is to run local http server serving the doc along with jupyter(lab) notebook server.

The branch uses thread parallelism to run sage doc server.

Try the branch with `sage --notebook=jupyterlab`. This runs a light-weight sage doc server at `http://localhost:<SAGE_DOC_LOCAL_PORT>`, where the environment variable `SAGE_DOC_LOCAL_PORT` defaults to 8000.

Set `export SAGE_DOC_SERVER_URL=https://doc.sagemath.org` before running `sage --notebook=jupyterlab` to use the public doc server. This will be useful for jupyterhub users.



Component: **notebook**

Author: **Kwankyu Lee**

Branch/Commit: **[public/run_doc_server](https://github.com/sagemath/sagetrac-mirror/tree/public/run_doc_server) @ [`70bdf46`](https://github.com/sagemath/sagetrac-mirror/commit/70bdf46e811b15d9886077ebdc5ce544626dc963)**

_Issue created by migration from https://trac.sagemath.org/ticket/34794_




Discussion:
Author: **Kwankyu Lee**
Description changed:
``````diff
--- 
+++ 
@@ -1 +1 @@
-
+Running jupyter notebook runs sage doc server along it so that sage documentation is available in notebook environment.
``````

Branch: **[u/klee/run_doc_server_along_with_jupyter_server](https://github.com/sagemath/sagetrac-mirror/tree/u/klee/run_doc_server_along_with_jupyter_server)**
Commit: **[`8b636bf`](https://github.com/sagemath/sagetrac-mirror/commit/8b636bf6ee8004ed21009876c5d0fa68be92325b)**
Changed branch from **[u/klee/run_doc_server_along_with_jupyter_server](https://github.com/sagemath/sagetrac-mirror/tree/u/klee/run_doc_server_along_with_jupyter_server)** to **[public/run_doc_server](https://github.com/sagemath/sagetrac-mirror/tree/public/run_doc_server)**
<div id="comment:3"></div>

New commits:
<table><tr><td><a href="https://github.com/sagemath/sagetrac-mirror/commit/8b636bf6ee8004ed21009876c5d0fa68be92325b"><code>8b636bf</code></a></td><td><code>Run sage doc server for notebooks</code></td></tr></table>

Description changed:
``````diff
--- 
+++ 
@@ -1 +1,5 @@
-Running jupyter notebook runs sage doc server along it so that sage documentation is available in notebook environment.
+Sage documentation links in `help` menu has been long broken in jupyterlab notebook interface.
+
+A proper fix  is to run local http server serving sage doc along with jupyter(lab) notebook server.
+
+
``````

Description changed:
``````diff
--- 
+++ 
@@ -1,5 +1,7 @@
-Sage documentation links in `help` menu has been long broken in jupyterlab notebook interface.
+Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface.
 
-A proper fix  is to run local http server serving sage doc along with jupyter(lab) notebook server.
+A proper fix is to run local http server serving sage doc along with jupyter(lab) notebook server.
+
+The branch uses thread parallelism to run sage doc server.
 
 
``````

Description changed:
``````diff
--- 
+++ 
@@ -4,4 +4,6 @@
 
 The branch uses thread parallelism to run sage doc server.
 
+Try the branch with `sage --notebook=jupyterlab`
 
+
``````

Description changed:
``````diff
--- 
+++ 
@@ -1,6 +1,6 @@
-Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface.
+Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface. By the way, they work well in jupyter notebook interface.
 
-A proper fix is to run local http server serving sage doc along with jupyter(lab) notebook server.
+Jupyterlab loads local files (sage documentation files) in `iframe` tag. This is problematic and it seems hopeless to make this work. A proper way is to run local http server serving the doc along with jupyter(lab) notebook server.
 
 The branch uses thread parallelism to run sage doc server.
 
``````

Changed commit from **[`8b636bf`](https://github.com/sagemath/sagetrac-mirror/commit/8b636bf6ee8004ed21009876c5d0fa68be92325b)** to **[`f3bf182`](https://github.com/sagemath/sagetrac-mirror/commit/f3bf1827a8720af3b81b657448f0e38d1cc3b798)**
<div id="comment:8"></div>

Branch pushed to git repo; I updated commit sha1. New commits:
<table><tr><td><a href="https://github.com/sagemath/sagetrac-mirror/commit/f3bf1827a8720af3b81b657448f0e38d1cc3b798"><code>f3bf182</code></a></td><td><code>Edit messages</code></td></tr></table>

<div id="comment:9"></div>

Branch pushed to git repo; I updated commit sha1. New commits:
<table><tr><td><a href="https://github.com/sagemath/sagetrac-mirror/commit/70bdf46e811b15d9886077ebdc5ce544626dc963"><code>70bdf46</code></a></td><td><code>Support SAGE_DOC_SERVER_URL for non-local doc server</code></td></tr></table>

Changed commit from **[`f3bf182`](https://github.com/sagemath/sagetrac-mirror/commit/f3bf1827a8720af3b81b657448f0e38d1cc3b798)** to **[`70bdf46`](https://github.com/sagemath/sagetrac-mirror/commit/70bdf46e811b15d9886077ebdc5ce544626dc963)**
Description changed:
``````diff
--- 
+++ 
@@ -4,6 +4,8 @@
 
 The branch uses thread parallelism to run sage doc server.
 
-Try the branch with `sage --notebook=jupyterlab`
+Try the branch with `sage --notebook=jupyterlab`. This runs a light-weight sage doc server at `http://localhost:<SAGE_DOC_LOCAL_PORT>`, where the environment variable `SAGE_DOC_LOCAL_PORT` defaults to 8000.
+
+Set `export SAGE_DOC_SERVER_URL=https://doc.sagemath.org` before running `sage --notebook=jupyterlab` to use the public doc server. This will be useful for jupyterhub users.
 
 
``````

Description changed:
``````diff
--- 
+++ 
@@ -1,4 +1,4 @@
-Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface. By the way, they work well in jupyter notebook interface.
+Sage documentation links in `help` menu have been long broken in jupyterlab notebook interface, although they work fine in jupyter notebook interface.
 
 Jupyterlab loads local files (sage documentation files) in `iframe` tag. This is problematic and it seems hopeless to make this work. A proper way is to run local http server serving the doc along with jupyter(lab) notebook server.
 
``````


Resolving patch:
diff --git a/src/sage/env.py b/src/sage/env.py
--- a/src/sage/env.py
+++ b/src/sage/env.py
@@ -187,6 +187,11 @@ def var(key: str, *fallbacks: Optional[str], force: bool = False) -> Optional[st
 SAGE_PKGS = var("SAGE_PKGS", join(SAGE_ROOT, "build", "pkgs"))
 SAGE_ROOT_GIT = var("SAGE_ROOT_GIT", join(SAGE_ROOT, ".git"))
 
+# Sage doc server (local server with PORT if URL is not given)
+SAGE_DOC_SERVER_URL = var("SAGE_DOC_SERVER_URL")
+# The default port is 0 so that the system will assign a random unused port > 1024
+SAGE_DOC_LOCAL_PORT = var("SAGE_DOC_LOCAL_PORT", "0")
+
 # ~/.sage
 DOT_SAGE = var("DOT_SAGE", join(os.environ.get("HOME"), ".sage"))
 SAGE_STARTUP_FILE = var("SAGE_STARTUP_FILE", join(DOT_SAGE, "init.sage"))
diff --git a/src/sage/repl/ipython_kernel/kernel.py b/src/sage/repl/ipython_kernel/kernel.py
--- a/src/sage/repl/ipython_kernel/kernel.py
+++ b/src/sage/repl/ipython_kernel/kernel.py
@@ -100,62 +100,68 @@ def help_links(self):
             sage: sk = SageKernel.__new__(SageKernel)
             sage: sk.help_links
             [{'text': 'Sage Documentation',
-              'url': 'https://doc.sagemath.org/html/en/index.html'},
+              'url': '.../html/en/index.html'},
              ...]
         """
-        # DEPRECATED: The URLs in the form 'kernelspecs/...' were used for
-        # classical Jupyter notebooks. For instance,
-        #
-        #  'kernelspecs/sagemath/doc/html/en/index.html'
-        #
-        # is constructed by kernel_url('doc/html/en/index.html'), but these
-        # URLs of local files don't work for JupyterLab. Hence all URLs here
-        # have been replaced with URLs of online documents.
-
-        from sage.repl.ipython_kernel.install import SageKernelSpec
-        identifier = SageKernelSpec.identifier()
-
-        def kernel_url(x):
-            # URLs starting with 'kernelspecs' are prepended by the
-            # browser with the appropriate path
-            return 'kernelspecs/{0}/{1}'.format(identifier, x)
+        # A Sage doc server starts when Jupyter notebook launches if the Sage
+        # documentation is available locally.  See the corresponding code in
+        # src/bin/sage-notebook.
+
+        from sage.env import SAGE_DOC_SERVER_URL
+        from sage.features.sagemath import sagemath_doc_html
+
+        if SAGE_DOC_SERVER_URL:
+            def doc_url(path):
+                return f'{SAGE_DOC_SERVER_URL}/{path}'
+        elif sagemath_doc_html().is_present():
+            from sage.env import SAGE_DOC_LOCAL_PORT as port
+
+            def doc_url(path):
+                return f'http://127.0.0.1:{port}/{path}'
+        else:
+            def doc_url(path):
+                return f'https://doc.sagemath.org/{path}'
 
         return [
             {
                 'text': 'Sage Documentation',
-                'url': "https://doc.sagemath.org/html/en/index.html",
+                'url': doc_url('html/en/index.html'),
             },
             {
                 'text': 'A Tour of Sage',
-                'url': "https://doc.sagemath.org/html/en/a_tour_of_sage/index.html",
+                'url': doc_url('html/en/a_tour_of_sage/index.html'),
             },
             {
                 'text': 'Tutorial',
-                'url': "https://doc.sagemath.org/html/en/tutorial/index.html",
+                'url': doc_url('html/en/tutorial/index.html'),
             },
             {
                 'text': 'Thematic Tutorials',
-                'url': "https://doc.sagemath.org/html/en/thematic_tutorials/index.html",
+                'url': doc_url('html/en/thematic_tutorials/index.html'),
             },
             {
                 'text': 'PREP Tutorials',
-                'url': "https://doc.sagemath.org/html/en/prep/index.html",
+                'url': doc_url('html/en/prep/index.html'),
             },
             {
                 'text': 'Constructions',
-                'url': "https://doc.sagemath.org/html/en/constructions/index.html",
+                'url': doc_url('html/en/constructions/index.html'),
             },
             {
                 'text': 'FAQ',
-                'url': "https://doc.sagemath.org/html/en/faq/index.html",
+                'url': doc_url('html/en/faq/index.html'),
+            },
+            {
+                'text': 'Reference Manual',
+                'url': doc_url('html/en/reference/index.html'),
             },
             {
-                'text': 'Reference',
-                'url': "https://doc.sagemath.org/html/en/reference/index.html",
+                'text': "Installation Guide",
+                'url': doc_url('html/en/installation/index.html'),
             },
             {
-                'text': "Developer's Guide",
-                'url': "https://doc.sagemath.org/html/en/developer/index.html",
+                'text': "Developer Guide",
+                'url': doc_url('html/en/developer/index.html'),
             },
             {
                 'text': "Python",


Test patch: