Revive sage live doc using jupyter-sphinx

.github/workflows/doc-build.yml

@@ -102,6 +102,8 @@ jobs:
         run: |
           set -ex
           export SAGE_USE_CDNS=yes
+          export SAGE_LIVE_DOC=yes
+          export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env/dev
           mv /sage/local/share/doc/sage/html/en/.git /sage/.git-doc
           make doc-clean doc-uninstall
           mkdir -p /sage/local/share/doc/sage/html/en/ && mv /sage/.git-doc /sage/local/share/doc/sage/html/en/.git

build/pkgs/jupyter_sphinx/checksums.ini

@@ -1,5 +1,5 @@
 tarball=jupyter_sphinx-VERSION.tar.gz
-sha1=241f6dfcd3aae4f44f330e2ba76480011b382d3d
-md5=e7ab370d9793be5b20bce5447ccbd45b
-cksum=2021246952
+sha1=fb2abdd5e35da0886b12d45a6373c4dbcc24b244
+md5=130daa6be810976c9f8e30aa04011e50
+cksum=2882523000
 upstream_url=https://pypi.io/packages/source/j/jupyter_sphinx/jupyter_sphinx-VERSION.tar.gz

build/pkgs/jupyter_sphinx/package-version.txt

@@ -1 +1 @@
-0.3.2
+0.4.0.p0

build/pkgs/jupyter_sphinx/patches/0001-Patch-for-sage-live-doc.patch

@@ -0,0 +1,57 @@
+From 5bffbe38302c695123779f87300d84090b4bd118 Mon Sep 17 00:00:00 2001
+From: Kwankyu Lee <[email protected]>
+Date: Mon, 28 Aug 2023 00:18:59 +0900
+Subject: [PATCH] Patch for sage live doc
+
+---
+ jupyter_sphinx/__init__.py |  4 ++--
+ jupyter_sphinx/execute.py  | 11 +++++++++++
+ 2 files changed, 13 insertions(+), 2 deletions(-)
+
+diff --git a/jupyter_sphinx/__init__.py b/jupyter_sphinx/__init__.py
+index 34af884..b7ca8ee 100644
+--- a/jupyter_sphinx/__init__.py
++++ b/jupyter_sphinx/__init__.py
+@@ -31,7 +31,7 @@ from .thebelab import ThebeButton, ThebeButtonNode, ThebeOutputNode, ThebeSource
+ REQUIRE_URL_DEFAULT = (
+     "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"
+ )
+-THEBELAB_URL_DEFAULT = "https://unpkg.com/thebelab@^0.4.0"
++THEBELAB_URL_DEFAULT = "https://unpkg.com/thebe@latest/lib/index.js"
+
+ logger = logging.getLogger(__name__)
+
+@@ -186,7 +186,7 @@ def setup(app):
+     app.add_config_value("jupyter_sphinx_embed_url", None, "html")
+
+     # thebelab config, can be either a filename or a dict
+-    app.add_config_value("jupyter_sphinx_thebelab_config", None, "html")
++    app.add_config_value("jupyter_sphinx_thebelab_config", None, "env")
+     app.add_config_value("jupyter_sphinx_thebelab_url", THEBELAB_URL_DEFAULT, "html")
+
+     # linenos config
+diff --git a/jupyter_sphinx/execute.py b/jupyter_sphinx/execute.py
+index 558a26b..de44455 100644
+--- a/jupyter_sphinx/execute.py
++++ b/jupyter_sphinx/execute.py
+@@ -152,6 +152,17 @@ class ExecuteJupyterCells(SphinxTransform):
+                 kernel_name = default_kernel
+                 file_name = next(default_names)
+
++            # Save time when jupyter notebook execution is not necessary
++            if not any(not "execute" in node or node["execute"] for node in nodes):
++                # mimics empty cell output for each node
++                for node in nodes:
++                    source = node.children[0]
++                    source.attributes["classes"].append("code_cell")
++                    node.attributes["cm_language"] = kernel_name
++                    node += CellOutputNode(classes=["cell_output"])
++                    apply_styling(node, thebe_config)
++                continue
++
+             # Add empty placeholder cells for non-executed nodes so nodes
+             # and cells can be zipped and the provided input/output
+             # can be inserted later
+-- 
+2.42.0
+

src/doc/common/static/custom-codemirror-monokai.css

@@ -0,0 +1,42 @@
+/* from https://codemirror.net/5/theme/monokai.css */
+/* Based on Sublime Text's Monokai theme */
+
+.cm-s-monokai.CodeMirror { background: #272822; color: #f8f8f2; }
+.cm-s-monokai div.CodeMirror-selected { background: #49483E; }
+.cm-s-monokai .CodeMirror-line::selection, .cm-s-monokai .CodeMirror-line > span::selection, .cm-s-monokai .CodeMirror-line > span > span::selection { background: rgba(73, 72, 62, .99); }
+.cm-s-monokai .CodeMirror-line::-moz-selection, .cm-s-monokai .CodeMirror-line > span::-moz-selection, .cm-s-monokai .CodeMirror-line > span > span::-moz-selection { background: rgba(73, 72, 62, .99); }
+.cm-s-monokai .CodeMirror-gutters { background: #272822; border-right: 0px; }
+.cm-s-monokai .CodeMirror-guttermarker { color: white; }
+.cm-s-monokai .CodeMirror-guttermarker-subtle { color: #d0d0d0; }
+.cm-s-monokai .CodeMirror-linenumber { color: #d0d0d0; }
+.cm-s-monokai .CodeMirror-cursor { border-left: 1px solid #f8f8f0; }
+
+.cm-s-monokai span.cm-comment { color: #75715e; }
+.cm-s-monokai span.cm-atom { color: #ae81ff; }
+.cm-s-monokai span.cm-number { color: #ae81ff; }
+
+.cm-s-monokai span.cm-comment.cm-attribute { color: #97b757; }
+.cm-s-monokai span.cm-comment.cm-def { color: #bc9262; }
+.cm-s-monokai span.cm-comment.cm-tag { color: #bc6283; }
+.cm-s-monokai span.cm-comment.cm-type { color: #5998a6; }
+
+.cm-s-monokai span.cm-property, .cm-s-monokai span.cm-attribute { color: #a6e22e; }
+.cm-s-monokai span.cm-keyword { color: #f92672; }
+.cm-s-monokai span.cm-builtin { color: #66d9ef; }
+.cm-s-monokai span.cm-string { color: #e6db74; }
+
+.cm-s-monokai span.cm-variable { color: #f8f8f2; }
+.cm-s-monokai span.cm-variable-2 { color: #9effff; }
+.cm-s-monokai span.cm-variable-3, .cm-s-monokai span.cm-type { color: #66d9ef; }
+.cm-s-monokai span.cm-def { color: #fd971f; }
+.cm-s-monokai span.cm-bracket { color: #f8f8f2; }
+.cm-s-monokai span.cm-tag { color: #f92672; }
+.cm-s-monokai span.cm-header { color: #ae81ff; }
+.cm-s-monokai span.cm-link { color: #ae81ff; }
+.cm-s-monokai span.cm-error { background: #f92672; color: #f8f8f0; }
+
+.cm-s-monokai .CodeMirror-activeline-background { background: #373831; }
+.cm-s-monokai .CodeMirror-matchingbracket {
+  text-decoration: underline;
+  color: white !important;
+}

src/doc/common/static/custom-jupyter-sphinx.css

@@ -0,0 +1,140 @@
+div.jupyter_container {
+  margin: .5rem 0;
+}
+
+div.jupyter_container + div.jupyter_container {
+  margin: 0 0 .5rem 0;
+}
+
+div.jupyter_container div.cell_input pre {
+  margin: .5rem;
+}
+
+div.jupyter_container div.cell_output div.output {
+  margin: .5rem;
+}
+
+.thebelab-cell .jp-OutputArea {
+  margin: 0 .5rem;
+}
+
+.thebelab-cell .jp-OutputArea-output {
+  margin: 0 0 .5rem 0;
+  overflow-x: auto;
+}
+
+.thebelab-button {
+  margin: .5rem 0 .5rem .5rem;
+  padding: 0 .5rem;
+  min-width: 2rem;
+}
+
+.thebelab-button:active {
+  color: #0f0fff;
+}
+
+.thebelab-busy {
+  margin-left: .5rem;
+}
+
+#thebelab-activate-button {
+  position: fixed;
+  right: -5.1rem;
+  top: calc(50% - 1.5rem);
+  width: 6rem;
+  border-radius: 1rem;
+  transition-property: right;
+  transition-duration: 300ms;
+  transition-timing-function: ease-out;
+  z-index: 100;
+}
+
+#thebelab-activate-button:hover {
+  right: .4rem;
+}
+
+#thebelab-activate-button:active {
+  color: #0f0fff;
+}
+
+body[data-theme="dark"] {
+  .jupyter_container {
+    color: white;
+    background-color: black;
+  }
+
+  .jupyter_container .highlight {
+    background-color: black;
+  }
+
+  .thebelab-button {
+    color: #d0d0d0;
+    background-color: #383838;
+  }
+
+  .thebelab-button:active {
+    color: #368ce2;
+  }
+
+  #thebelab-activate-button {
+    background-color: #383838;
+  }
+
+  #thebelab-activate-button:active {
+    color: #368ce2;
+  }
+
+  .thebelab-cell .jp-OutputArea-output {
+    color: white;
+    background-color: black;
+  }
+
+  .thebelab-cell .jp-OutputArea-output pre {
+    color: white;
+    background-color: black;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+ body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */
+  .jupyter_container {
+    color: white;
+    background-color: black;
+  }
+
+  .jupyter_container .highlight {
+    background-color: black;
+  }
+
+  .thebelab-button {
+    color: #d0d0d0;
+    background-color: #383838;
+  }
+
+  .thebelab-button:active {
+    color: #368ce2;
+  }
+
+  #thebelab-activate-button {
+    background-color: #383838;
+  }
+
+  #thebelab-activate-button:active {
+    color: #368ce2;
+  }
+
+  .thebelab-cell .jp-OutputArea-output {
+    color: white;
+    background-color: black;
+  }
+
+  .thebelab-cell .jp-OutputArea-output pre {
+    color: white;
+    background-color: black;
+  }
+ }
+}
+
+
+
+

src/doc/common/static/jupyter-sphinx-furo.js

@@ -0,0 +1,114 @@
+// Change the editor theme according to the furo light/dark/auto mode
+function changeTheme(editor, theme) {
+  if (theme === 'dark') {
+    editor.setOption('theme', 'monokai'); // the same with pygments dark style in conf.py
+  } else if (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+    editor.setOption('theme', 'monokai');
+  } else {
+    editor.setOption('theme', 'default');
+  }
+}
+
+// Change the editor theme of all CodeMirror cells
+function changeThemeAll(theme) {
+  const querySet = document.querySelectorAll('.CodeMirror');
+  for (var i = 0; i < querySet.length; i++) {
+    changeTheme(querySet[i].CodeMirror, theme);
+  }
+}
+
+// Use the theme data of the body element set by setTheme function
+// defined in https://github.com/pradyunsg/furo/blob/main/src/furo/assets/scripts/furo.js
+const body = document.body;
+const observer1 = new MutationObserver((mutationsList) => {
+  for (let mutation of mutationsList) {
+    if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') {
+      const theme = body.dataset.theme;
+      changeThemeAll(theme);
+    }
+  }
+});
+observer1.observe(body, { attributes: true });
+
+
+// In the furo auto mode, we watch prefers-color-scheme and use the theme data
+// of the body element to change the CodeMirror editor theme
+const prefersDarkMode = window.matchMedia('(prefers-color-scheme: dark)');
+
+function handlePrefersColorSchemeChange(e) {
+  const theme = body.dataset.theme;
+  if (theme === 'auto') {
+    changeThemeAll(theme);
+  }
+}
+
+prefersDarkMode.addEventListener('change', handlePrefersColorSchemeChange);
+
+
+// Change the editor theme of a new CodeMirror cell.
+const callback = function(mutationsList, observer) {
+  for(const mutation of mutationsList) {
+    if (mutation.type === 'childList') {
+      const theme = body.dataset.theme;
+      for (const addedNode of mutation.addedNodes) {
+        if (addedNode.classList && addedNode.classList.contains('CodeMirror')) {
+          changeTheme(addedNode.CodeMirror, theme);
+        }}}}};
+const observer2 = new MutationObserver(callback);
+observer2.observe(document.getElementsByClassName("content")[0], { childList: true, subtree: true });
+
+
+// Listen to the kernel status changes
+// https://thebe.readthedocs.io/en/stable/events.html
+thebelab.on("status", function (evt, data) {
+  if (data.status === 'building') {
+    const elements = document.querySelectorAll('.thebelab-cell');
+    elements.forEach(element => {
+      element.style.filter = 'opacity(50%)';
+    });
+    const element = document.getElementById("thebelab-activate-button");
+    element.innerHTML = "Building";
+    element.style.right = '.4rem';
+  }
+  else if (data.status === 'built') {
+    const elements = document.querySelectorAll('.thebelab-cell');
+    elements.forEach(element => {
+      element.style.filter = 'opacity(60%)';
+    });
+    const element = document.getElementById("thebelab-activate-button");
+    element.innerHTML = "Built";
+    element.style.right = '.4rem';
+  }
+  else if (data.status === 'launching') {
+    const elements = document.querySelectorAll('.thebelab-cell');
+    elements.forEach(element => {
+      element.style.filter = 'opacity(70%)';
+    });
+    const element = document.getElementById("thebelab-activate-button");
+    element.innerHTML = "Launching";
+    element.style.right = '.4rem';
+  }
+  else if (data.status === 'failed') {
+    const elements = document.querySelectorAll('.thebelab-cell');
+    elements.forEach(element => {
+      element.style.filter = 'opacity(50%)';
+    });
+    const element = document.getElementById("thebelab-activate-button");
+    element.innerHTML = 'Failed: ' + data.message;
+    element.style.right = '.4rem';
+    element.style.width = 'auto';
+    element.style.color = 'red';
+  }
+  else if (data.status === 'ready') {
+    const elements = document.querySelectorAll('.thebelab-cell');
+    elements.forEach(element => {
+      element.style.filter = 'opacity(100%)';
+    });
+    const element = document.getElementById("thebelab-activate-button");
+    element.innerHTML = "Ready";
+    element.style.right = null;
+    // Run custom code when the kernel is ready
+    const kernel = data.kernel;
+    kernel.requestExecute({code: "%display latex"});
+  }
+});