Rework on live sage documentation #33320
Milestone
Comments
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Dependencies: #33507 |
|
comment:4
Achieved by #33507. |
|
comment:5
Isn't the goal that every cell on every documentation page can be activated? |
This comment has been minimized.
This comment has been minimized.
kwankyu
changed the title
|
comment:7
Replying to @mkoeppe:
Okay. I felt I was missing something. |
|
Author: Kwankyu Lee |
|
Branch: u/klee/33320 |
|
Branch pushed to git repo; I updated commit sha1. Last 10 new commits:
|
|
Commit: |
|
Changed commit from |
|
Changed branch from u/klee/33320 to public/33320 |
|
Branch pushed to git repo; I updated commit sha1. Last 10 new commits:
|
|
Commit: |
|
comment:13
To use a local jupyter server for live doc: in and rebuild the doc. To view the live doc, run and open the doc. |
|
Branch pushed to git repo; I updated commit sha1. New commits:
|
|
comment:87
Replying to @kwankyu:
Using live docs, I realized that many example code blocks in sage documentation are not ready for live run, and frequently needs user's editing before run. Hence I changed my mind, and the last commit makes code blocks editable. |
|
comment:88
Note that code-mirror configuration doesn't work. It seems an issue of the current thebe. |
|
comment:89
Note also that it is now a lot easy to copy-paste code blocks into jupyter :) |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
comment:95
The last commit fixes a bug that causes a failure when |
This comment has been minimized.
This comment has been minimized.
|
Branch pushed to git repo; I updated commit sha1. New commits:
|
|
Dependencies: #33763 |
13 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 Thebe was not working in our sage documentation, we removed it from sage (see #33309, #33529) and introduced a new tool jupyter-sphinx in #33507.
As we move to the new tool, the ticket
was closed.
Based on the efforts of #24593, the goal of this ticket is to deliver the live documentation using jupyter-sphinx so that every code blocks on every documentation page can be activated.
This ticket patches
jupyter-sphinxwithDepends on #33763
CC: @jhpalmieri
Component: documentation
Author: Kwankyu Lee
Branch/Commit: public/33320 @
f5dff43Issue created by migration from https://trac.sagemath.org/ticket/33320
The text was updated successfully, but these errors were encountered: