gh-36144: Revive sage live doc using jupyter-sphinx
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->
We fix #33320 and #24367.
We also upgrade jupyter-sphinx standard package to the latest version
0.4.0: https://github.com/jupyter/jupyter-sphinx/releases/tag/v0.4.0,
and patch it to facilitate live doc.
By default, live doc depends on https://github.com/sagemath/sage-binder-
env for binder (remote jupyter server).
To showcase the live doc, we edited "A Tour of Sage" doc and some parts
of sage doc. Visit
- https://deploy-preview-36144--sagemath-
tobias.netlify.app/a_tour_of_sage or
- https://deploy-preview-36144--sagemath-
tobias.netlify.app/tutorial/latex (edited to resolve #24367)
**Click the activate button to activate live doc** The button is hidden
to the right middle side of the browser. After clicked, the activate
button shows the status of the launching kernel.
**Be patient if the kernel loads slow. It may take several minutes.**
Sometimes it may be stuck in the "launching" state. In that case, reload
the page and try again.
Note that `%display latex` is the default. You should use `%display
plain` to get plain textual output.
## Preparation
```
./sage -i jupyterlab
```
If things do not work as expected, first remove the existing
documentation by
```
make doc-clean doc-uninstall
```
## Build static doc
```
export SAGE_LIVE_DOC=no # default
make -j4
```
## Build live doc with the default Binder repo
```
export SAGE_LIVE_DOC=yes
export SAGE_JUPYTER_SERVER=binder # default
make -j4
```
## Build live doc with a custom Binder repo
```
export SAGE_LIVE_DOC=yes
export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env # default
make -j4
```
The kernel is "sagemath".
## Build live doc with a local server
```
export SAGE_LIVE_DOC=yes
export SAGE_JUPYTER_SERVER=http://localhost:8889
export SAGE_JUPYTER_SERVER_TOKEN=secret # default
make -j4
```
and run a local jupyter server before browsing the documentation.
```
./sage --notebook=jupyterlab \
--ServerApp.token='secret' \
--ServerApp.allow_origin='null' \
--ServerApp.disable_check_xsrf=true \
--ServerApp.port=8889 \
--ServerApp.open_browser=false
```
## Build live doc selectively
First build static doc
```
make -j4
```
and then build live doc selectively either by
```
./sage --docbuild --live-doc a_tour_of_sage html
```
or
```
export SAGE_JUPYTER_SERVER=http://localhost:8889
export SAGE_JUPYTER_SERVER_TOKEN=secret # default
./sage --docbuild --live-doc a_tour_of_sage html
```
with a local server.
### :memo: Checklist
<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->
- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.
Related upstream issues:
- https://github.com/jupyter/jupyter-sphinx/issues/201
- https://github.com/jupyter/jupyter-sphinx/pull/231
URL: https://github.com/sagemath/sage/pull/36144
Reported by: Kwankyu Lee
Reviewer(s): github-actions[bot], Kwankyu Lee, Matthias Köppe
