-
-
Notifications
You must be signed in to change notification settings - Fork 476
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revive sage live doc using jupyter-sphinx #36144
Revive sage live doc using jupyter-sphinx #36144
Conversation
Try this. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
kwankyu requested changes for this PR
I've merged sagemath/sage-binder-env#16 - can you use the official thing now? |
Great! Thanks. |
Still the same |
which browser are you testing with? My tests are with Chrome on macOS; and the dark-mode-screenshot tool uses Chromium |
Same problem also with Safari on macOS |
chrome on macos sonoma |
There's no problem on this page: https://deploy-preview-36144--sagemath-tobias.netlify.app/a_tour_of_sage/ The problem is with this page: https://deploy-preview-36144--sagemath-tobias.netlify.app/tutorial/latex |
The same on this page: https://deploy-preview-36144--sagemath-tobias.netlify.app/tutorial/latex |
The portion of the page that you screenshotted is also OK for me. The problem shows, as my previous screenshots have shown, a bit further down. |
Yes, I got it! I must have fixed this before... or no... I will check. No, right. |
Basically we are fixing jupyter-sphinx that doesn't support dark mode. As the maintainer is not very responsive, we have to deal with that here. Should be fixed now. Thanks for catching this! |
I missed that before... |
Yes! It's working! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a great improvement. Let's merge it and make sure that it becomes available in our documentation for 10.2
As live doc is totally optional, it is left to users and the project how to use it. Currently a major obstacle is of course slow (and sometimes failing) kernel loading from the Binder repo. It seems that there is not much left to do in this regard on our side, and perhaps neither on Binder side too. For individual users, running a local server is the best way to use live doc. Running and experimenting with the code examples right in the live doc would improve accessibility of the vast features of Sage. In this regard, many code examples should be refactored to facilitate live doc. For the project, I am not sure. I hope that live doc be available in all online documentation, but because of the major obstacle, this needs more thought and discussion. |
Thank you all! |
Documentation preview for this PR (built with commit 857741c; changes) is ready! 🎉 |
<!-- ^^^^^ 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 sagemath#1234" use "Introduce new method to calculate 1+1" --> <!-- Describe your changes here in detail --> We fix sagemath#33320 and sagemath#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 sagemath#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. ### 📝 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: - jupyter/jupyter-sphinx#201 - jupyter/jupyter-sphinx#231 URL: sagemath#36144 Reported by: Kwankyu Lee Reviewer(s): github-actions[bot], Kwankyu Lee, Matthias Köppe
<!-- ^^^^^ 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 sagemath#1234" use "Introduce new method to calculate 1+1" --> <!-- Describe your changes here in detail --> We fix sagemath#33320 and sagemath#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 sagemath#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. ### 📝 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: - jupyter/jupyter-sphinx#201 - jupyter/jupyter-sphinx#231 URL: sagemath#36144 Reported by: Kwankyu Lee Reviewer(s): github-actions[bot], Kwankyu Lee, Matthias Köppe
<!-- ^^^^^ 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 sagemath#1234" use "Introduce new method to calculate 1+1" --> <!-- Describe your changes here in detail --> We fix sagemath#33320 and sagemath#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 sagemath#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. ### 📝 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: - jupyter/jupyter-sphinx#201 - jupyter/jupyter-sphinx#231 URL: sagemath#36144 Reported by: Kwankyu Lee Reviewer(s): github-actions[bot], Kwankyu Lee, Matthias Köppe
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
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
If things do not work as expected, first remove the existing documentation by
Build static doc
Build live doc with the default Binder repo
Build live doc with a custom Binder repo
The kernel is "sagemath".
Build live doc with a local server
and run a local jupyter server before browsing the documentation.
Build live doc selectively
First build static doc
and then build live doc selectively either by
or
with a local server.
📝 Checklist
Related upstream issues: