Confusing documentation on MathJax in light of use in Jupyter notebook #24367
Labels
Milestone
Comments
|
comment:4
Retargeting some of my tickets (somewhat optimistically for now). |
|
comment:5
Removing most of the rest of my open tickets out of the 8.7 milestone, which should be closed. |
|
Changed keywords from none to sd111 |
5 tasks
5 tasks
vbraun
pushed a commit
to vbraun/sage
that referenced
this issue
Oct 28, 2023
<!-- ^^^^^ 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
vbraun
pushed a commit
to vbraun/sage
that referenced
this issue
Oct 28, 2023
<!-- ^^^^^ 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
vbraun
pushed a commit
to vbraun/sage
that referenced
this issue
Oct 29, 2023
<!-- ^^^^^ 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
As pointed out to me in this issue, this documentation page is a little confusing as to how use of the
MathJaxclass relates to displaying LaTeX representations in the Jupyter notebook.This confusion is increased by the fact that Jupyter doesn't display objects' latex repr by default (I'm not sure if that's the case or not for the classic Sage NB to which these docs were likely written). The user was confused into believing that the repr of a
MathJaxobject should actually be rendered, and not display the raw HTML.This section should probably be rewritten since it's confusing usage instructions with implementation details that won't be interesting to a casual user. I think these examples of using the
MathJaxclass should be removed and/or moved to the class's API documentation (which could perhaps be linked to, but not further discussed?)CC: @slel @kwankyu
Component: documentation
Keywords: sd111
Issue created by migration from https://trac.sagemath.org/ticket/24367
The text was updated successfully, but these errors were encountered: