Skip to content
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

Rework on live sage documentation #33320

Closed
kwankyu opened this issue Feb 10, 2022 · 123 comments · Fixed by #36144
Closed

Rework on live sage documentation #33320

kwankyu opened this issue Feb 10, 2022 · 123 comments · Fixed by #36144

Comments

@kwankyu
Copy link
Collaborator

kwankyu commented Feb 10, 2022

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-sphinx with

Depends on #33763

CC: @jhpalmieri

Component: documentation

Author: Kwankyu Lee

Branch/Commit: public/33320 @ f5dff43

Issue created by migration from https://trac.sagemath.org/ticket/33320

@kwankyu kwankyu added this to the sage-9.6 milestone Feb 10, 2022
@kwankyu

This comment has been minimized.

@kwankyu

This comment has been minimized.

@mkoeppe
Copy link
Contributor

mkoeppe commented Mar 22, 2022

Dependencies: #33507

@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 22, 2022

comment:4

Achieved by #33507.

@kwankyu kwankyu removed this from the sage-9.6 milestone Mar 22, 2022
@mkoeppe
Copy link
Contributor

mkoeppe commented Mar 22, 2022

comment:5

Isn't the goal that every cell on every documentation page can be activated?

@kwankyu

This comment has been minimized.

@kwankyu kwankyu changed the title Rework on Thebe for live sage documentation Rework on live sage documentation Mar 23, 2022
@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 23, 2022

comment:7

Replying to @mkoeppe:

Isn't the goal that every cell on every documentation page can be activated?

Okay. I felt I was missing something.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 24, 2022

Author: Kwankyu Lee

@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 24, 2022

Branch: u/klee/33320

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 24, 2022

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

018da51Position thebe button at right bottom
c619fa2Add Thebe kernel specs
72ae570Fix missing inventory file error
e499c2fUse sphinx_plot for pdf documentation
777e25eLive images only when requested
567730cPrevent duplicate code display
e881abcbuild/pkgs/thebe: Remove
9621c97build/pkgs/sagemath_doc_html/dependencies: Remove thebe
72c8378Merge #33529
1a47505Make examples alive

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 24, 2022

Commit: 1a47505

@kwankyu kwankyu added this to the sage-9.6 milestone Mar 24, 2022
@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 25, 2022

Changed commit from 1a47505 to none

@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 25, 2022

Changed branch from u/klee/33320 to public/33320

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 25, 2022

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

c619fa2Add Thebe kernel specs
72ae570Fix missing inventory file error
e499c2fUse sphinx_plot for pdf documentation
777e25eLive images only when requested
567730cPrevent duplicate code display
e881abcbuild/pkgs/thebe: Remove
9621c97build/pkgs/sagemath_doc_html/dependencies: Remove thebe
72c8378Merge #33529
1a47505Make examples alive
eac2d11Allow local server

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 25, 2022

Commit: eac2d11

@kwankyu
Copy link
Collaborator Author

kwankyu commented Mar 25, 2022

comment:13

To use a local jupyter server for live doc: in src/sage/docs/conf.py,

# comment out if local jupyter server is running
jupyter_sphinx_thebelab_config.update({
    'binderOptions': {
        'repo': "sagemath/sage-binder-env",
    },
})

and rebuild the doc.

To view the live doc, run

sage --notebook=jupyterlab --ServerApp.token='secret' --ServerApp.allow_origin='null' --ServerApp.disable_check_xsrf=true

and open the doc.

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 25, 2022

Changed commit from eac2d11 to abe64df

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Mar 25, 2022

Branch pushed to git repo; I updated commit sha1. New commits:

abe64dfIntroduce JUPYTER_SERVER environment variable

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Apr 13, 2022

Branch pushed to git repo; I updated commit sha1. New commits:

5420184Make code blocks editable

@kwankyu
Copy link
Collaborator Author

kwankyu commented Apr 13, 2022

comment:87

Replying to @kwankyu:

Replying to @mkoeppe:

One thing is that the interaction is very limited - one cannot edit the inputs, so all one can do is reproduce the result that the doctest is already showing.

I think this is the primary purpose of the documentation -- running the examples as they are. If they want to do variations, they should go to jupyter and copy-paste.

Of course, it is easy to allow user modifications. A couple of configuration changes. But first we have to decide what behavior we want.

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.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Apr 13, 2022

comment:88

Note that code-mirror configuration doesn't work. It seems an issue of the current thebe.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Apr 13, 2022

comment:89

Note also that it is now a lot easy to copy-paste code blocks into jupyter :)

@kwankyu

This comment has been minimized.

@kwankyu

This comment has been minimized.

@kwankyu

This comment has been minimized.

@kwankyu

This comment has been minimized.

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Apr 24, 2022

Changed commit from 5420184 to a5479ba

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Apr 24, 2022

Branch pushed to git repo; I updated commit sha1. New commits:

ee57bfcMerge branch develop
a5479baFix a bug in patching jupyter-sphinx

@kwankyu
Copy link
Collaborator Author

kwankyu commented Apr 24, 2022

comment:95

The last commit fixes a bug that causes a failure when .. JUPYTER_EXECUTE:: is directly used without execute tag.

@kwankyu

This comment has been minimized.

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Apr 25, 2022

Branch pushed to git repo; I updated commit sha1. New commits:

f5dff43Use jupyter-sphinx only for live doc

@sagetrac-git
Copy link
Mannequin

sagetrac-git mannequin commented Apr 25, 2022

Changed commit from a5479ba to f5dff43

@kwankyu
Copy link
Collaborator Author

kwankyu commented Apr 29, 2022

Dependencies: #33763

@mkoeppe mkoeppe modified the milestones: sage-9.7, sage-9.8 Aug 31, 2022
@mkoeppe mkoeppe removed this from the sage-9.8 milestone Jan 29, 2023
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
@vbraun vbraun closed this as completed in c59ebbb Oct 31, 2023
@mkoeppe mkoeppe added this to the sage-10.2 milestone Oct 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants