Closed nthiery closed 8 years ago
Description changed:
---
+++
@@ -1 +1,18 @@
+Thebe is a Jupyter javascript plugin for static sites that allows for rendering selected divs of the HTML as live cells connected to a Jupyter server:
+ https://oreillymedia.github.io/thebe/
+
+The idea is to use this technology to make
+
+Steps:
+- Configure Sphinx to add the Thebe javascript library in the static page
+- Configure Sphinx to add a small header to our html page with:
+ - Inclusion of the Thebe javascript
+ - Thebe configuration: which divs to make live, which server to use
+ - A button to turn on live cells
+ - Possibly a menu or other widgets for user customization of the server configuration
+- Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe.
+- Customize/configure Thebe to support Sage's doctest syntax:
+ - Stripping out the prompts
+ - Stripping out the included outputs (bonus: show the included outputs below the cell until the new output is computed)
+ - Bonus: support doctests with several commands by split into several cells
New commits:
19f31f8 | 20690: added some examples of sage code in a fast-to-compile document. DONT MERGE IN SAGE |
The current branch is not to be merged in Sage, as it contains some edits in the Sage's faq that are just here for quick testing (compiling the faq is fast!).
Description changed:
---
+++
@@ -5,14 +5,14 @@
The idea is to use this technology to make
Steps:
-- Configure Sphinx to add the Thebe javascript library in the static page
-- Configure Sphinx to add a small header to our html page with:
- - Inclusion of the Thebe javascript
- - Thebe configuration: which divs to make live, which server to use
- - A button to turn on live cells
- - Possibly a menu or other widgets for user customization of the server configuration
-- Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe.
+- [X] Configure Sphinx to add the Thebe javascript library in the static page
+- [/] Configure Sphinx to add a small header to our html page with:
+ - [X] Inclusion of the Thebe javascript
+ - [ ] Thebe configuration: which divs to make live, which server to use
+ - [ ] A button to activate live cells
+ - [ ] Possibly a menu or other widgets for user customization of the server configuration
+- [?] Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe.
- Customize/configure Thebe to support Sage's doctest syntax:
- - Stripping out the prompts
- - Stripping out the included outputs (bonus: show the included outputs below the cell until the new output is computed)
- - Bonus: support doctests with several commands by split into several cells
+ - [ ] Stripping out the prompts
+ - [ ] Stripping out the included outputs (bonus: show the included outputs below the cell until the new output is computed)
+ - [ ] Support doctests with several commands by split into several cells
Description changed:
---
+++
@@ -6,13 +6,18 @@
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
-- [/] Configure Sphinx to add a small header to our html page with:
+- [ / ] Configure Sphinx to add a small header to our html page with:
- [X] Inclusion of the Thebe javascript
- - [ ] Thebe configuration: which divs to make live, which server to use
- - [ ] A button to activate live cells
+ - [x] Thebe configuration: which divs to make live
+ Currently, we include all <pre> tags that contain sage:
+ - [ ] Thebe configuration: use the Jupyter instance serving the page
+ We use window.location.origin; is this the right thing to do?
+ - [ ] Only activate Thebe if running inside a Jupyter server
+ - [x] A button to activate live cells
- [ ] Possibly a menu or other widgets for user customization of the server configuration
- [?] Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe.
- Customize/configure Thebe to support Sage's doctest syntax:
- [ ] Stripping out the prompts
- [ ] Stripping out the included outputs (bonus: show the included outputs below the cell until the new output is computed)
- - [ ] Support doctests with several commands by split into several cells
+ - [ ] Support doctests with several commands by spliting into several cells
+
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
5016cd8 | 20690: First implementation of a live documentation in Jupyter using Thebe |
Description changed:
---
+++
@@ -1,23 +1,82 @@
-Thebe is a Jupyter javascript plugin for static sites that allows for rendering selected divs of the HTML as live cells connected to a Jupyter server:
+Thebe is a Jupyter javascript plugin for static sites that allows for
+rendering selected divs of the HTML as live cells connected to a
+Jupyter server:
https://oreillymedia.github.io/thebe/
-The idea is to use this technology to make
+The goal of this ticket is to use this technology to implement live
+documentation in the Jupyter notebook as we had in the legacy Sage
+notebook.
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
- [ / ] Configure Sphinx to add a small header to our html page with:
- [X] Inclusion of the Thebe javascript
- [x] Thebe configuration: which divs to make live
- Currently, we include all <pre> tags that contain sage:
+ Currently, we include all <pre> tags that contain the "sage:" prompt
+ TODO: shall we change to <pre> tags that start with the "sage:" prompt ?
- [ ] Thebe configuration: use the Jupyter instance serving the page
- We use window.location.origin; is this the right thing to do?
- - [ ] Only activate Thebe if running inside a Jupyter server
+ We currently use window.location.origin; is this the right thing to do?
+ - [x] Only activate Thebe if the page is served by a Jupyter instance
+ Currently we check that the protocol is http
- [x] A button to activate live cells
- - [ ] Possibly a menu or other widgets for user customization of the server configuration
-- [?] Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe.
-- Customize/configure Thebe to support Sage's doctest syntax:
- - [ ] Stripping out the prompts
- - [ ] Stripping out the included outputs (bonus: show the included outputs below the cell until the new output is computed)
+
+- [X] Configure the Jupyter notebook in Sage to somehow provide the
+ server configuration to Thebe (not needed in fact)
+
+- Preparse or customize/configure Thebe to support Sage's doctest syntax:
+ - [ ] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
+ - [ ] Strip out the outputs
+ Bonus: show the included outputs below the cell until the new output is computed
- [ ] Support doctests with several commands by spliting into several cells
+- Check what's the right way for including thebe.js in the Sage
+ sources. Should we have a spkg? (to be discussed at Sage Days 74
+ with Volker).
+
+Steps for later tickets:
+
+- [ ] Currently it takes 10s for 100 prompts while some sage files
+ contain up to 1000 prompts. Profile Thebe and optimize it or use
+ a separate thread to properly support large files.
+
+- [ ] Expand the activate button with a menu or other widgets for user
+ customization of the Jupyter server. This typically would
+ let the user choose between:
+ - tmpnb (will only be useful for Sage when tmpnb will include a
+ Sage kernel)
+ - A local Jupyter server
+ - Whichever Jupyter server the browser is currently connected to?
+ - a user specified server
+
+- [ ] Check whether Jupyter could be configured to dynamically
+ negotiate incoming connections that don't fall within the
+ -NotebookApp.allow_origin pattern, by opening a user dialog such
+ as "Page xxx requests starting a new kernel on this server; do
+ you accept? yes/no/always for this site"
+
+- [ ] Add support in Thebe for customizable (continuation) prompts, with
+ striping and splitting as above, and automatic setting of the kernel.
+ The customization option could look like:
+
+ ```
+ prompts = {
+ "sage: ": {continuations=["....:", "... "], kernel="sagemath"},
+ ">>>> ": {continuation="... ", kernel="python"}
+ }
+ ```
+
+- [ ] Contribute support for Thebe upstream in Sphinx, with:
+
+ - [ ] Explicit markup to specify which code blocks are editable
+ and with which kernel, or setup kernel auto-detection from
+ the prompt.
+
+ - [ ] The possibility for setting a default value for the above
+
+- [ ] Refactor the Sage sphinx configuration to use the above
+
+- [ ] Add support in Thebe for basic export to Jupyter notebooks. A
+ quality loss (in particular in terms of the hierarchical
+ structure) is acceptable.
+
Changed keywords from none to days77, jupyter, thebe, notebook
Description changed:
---
+++
@@ -7,6 +7,8 @@
The goal of this ticket is to use this technology to implement live
documentation in the Jupyter notebook as we had in the legacy Sage
notebook.
+
+Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML.
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
Description changed:
---
+++
@@ -8,7 +8,7 @@
documentation in the Jupyter notebook as we had in the legacy Sage
notebook.
-Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML.
+Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
Branch pushed to git repo; I updated commit sha1. New commits:
32c9e64 | 20690: Only show the activate button when there are cells to be activated |
d6aaed2 | 20690: Disable the activate button once clicked |
b5e95e4 | 20690: Factor out a thebe-sage setup function before complexifying it for upcoming functionalities |
07035fd | 20690: On live doc activation, hide expected results and add a Run button before them |
Everything seems to work (nice!). Some naive questions from a user point of view:
Less importantly:
why did you decide to have this "Run" and "Run Again" buttons? These do not exist in the standard Jupyter notebook. Would it be possible to simply remove them?
the cells are properly executed when pressing "Shift + Enter" but, contrarily to the case of the notebook, after pressing "Shift + Enter" the focus is kept in the same cell. Not sure that it is desirable to move the focus (since the next cell might be very far).
Description changed:
---
+++
@@ -12,31 +12,32 @@
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
-- [ / ] Configure Sphinx to add a small header to our html page with:
+- [X] Configure Sphinx to add a small header to our html page with:
- [X] Inclusion of the Thebe javascript
- - [x] Thebe configuration: which divs to make live
+ - [X] Thebe configuration: which divs to make live
Currently, we include all <pre> tags that contain the "sage:" prompt
TODO: shall we change to <pre> tags that start with the "sage:" prompt ?
- - [ ] Thebe configuration: use the Jupyter instance serving the page
- We currently use window.location.origin; is this the right thing to do?
- - [x] Only activate Thebe if the page is served by a Jupyter instance
- Currently we check that the protocol is http
- - [x] A button to activate live cells
+to do?
+- [X] Only activate Thebe if the page is served by a Jupyter instance
+ Currently we check that the protocol is http
+- [X] A button to activate live cells
- [X] Configure the Jupyter notebook in Sage to somehow provide the
server configuration to Thebe (not needed in fact)
- Preparse or customize/configure Thebe to support Sage's doctest syntax:
- [ ] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
- - [ ] Strip out the outputs
+ - [X] Strip out the outputs
Bonus: show the included outputs below the cell until the new output is computed
- - [ ] Support doctests with several commands by spliting into several cells
+ - [X] Support doctests with several commands by spliting into several cells
- Check what's the right way for including thebe.js in the Sage
sources. Should we have a spkg? (to be discussed at Sage Days 74
with Volker).
Steps for later tickets:
+
+- [ ] Configure Sphinx to add a small header to our html page with Thebe configuration: use the Jupyter instance serving the page. We currently use `window.location.origin`; is this the right thing?
- [ ] Currently it takes 10s for 100 prompts while some sage files
contain up to 1000 prompts. Profile Thebe and optimize it or use
@@ -53,7 +54,7 @@
- [ ] Check whether Jupyter could be configured to dynamically
negotiate incoming connections that don't fall within the
- -NotebookApp.allow_origin pattern, by opening a user dialog such
+ `-NotebookApp.allow_origin pattern`, by opening a user dialog such
as "Page xxx requests starting a new kernel on this server; do
you accept? yes/no/always for this site"
@@ -81,4 +82,3 @@
- [ ] Add support in Thebe for basic export to Jupyter notebooks. A
quality loss (in particular in terms of the hierarchical
structure) is acceptable.
-
Description changed:
---
+++
@@ -25,60 +25,14 @@
- [X] Configure the Jupyter notebook in Sage to somehow provide the
server configuration to Thebe (not needed in fact)
-- Preparse or customize/configure Thebe to support Sage's doctest syntax:
+- [/] Preparse or customize/configure Thebe to support Sage's doctest syntax:
- [ ] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
- [X] Strip out the outputs
Bonus: show the included outputs below the cell until the new output is computed
- [X] Support doctests with several commands by spliting into several cells
-- Check what's the right way for including thebe.js in the Sage
+- [X] Check what's the right way for including thebe.js in the Sage
sources. Should we have a spkg? (to be discussed at Sage Days 74
with Volker).
-Steps for later tickets:
-
-- [ ] Configure Sphinx to add a small header to our html page with Thebe configuration: use the Jupyter instance serving the page. We currently use `window.location.origin`; is this the right thing?
-
-- [ ] Currently it takes 10s for 100 prompts while some sage files
- contain up to 1000 prompts. Profile Thebe and optimize it or use
- a separate thread to properly support large files.
-
-- [ ] Expand the activate button with a menu or other widgets for user
- customization of the Jupyter server. This typically would
- let the user choose between:
- - tmpnb (will only be useful for Sage when tmpnb will include a
- Sage kernel)
- - A local Jupyter server
- - Whichever Jupyter server the browser is currently connected to?
- - a user specified server
-
-- [ ] Check whether Jupyter could be configured to dynamically
- negotiate incoming connections that don't fall within the
- `-NotebookApp.allow_origin pattern`, by opening a user dialog such
- as "Page xxx requests starting a new kernel on this server; do
- you accept? yes/no/always for this site"
-
-- [ ] Add support in Thebe for customizable (continuation) prompts, with
- striping and splitting as above, and automatic setting of the kernel.
- The customization option could look like:
-
- ```
- prompts = {
- "sage: ": {continuations=["....:", "... "], kernel="sagemath"},
- ">>>> ": {continuation="... ", kernel="python"}
- }
- ```
-
-- [ ] Contribute support for Thebe upstream in Sphinx, with:
-
- - [ ] Explicit markup to specify which code blocks are editable
- and with which kernel, or setup kernel auto-detection from
- the prompt.
-
- - [ ] The possibility for setting a default value for the above
-
-- [ ] Refactor the Sage sphinx configuration to use the above
-
-- [ ] Add support in Thebe for basic export to Jupyter notebooks. A
- quality loss (in particular in terms of the hierarchical
- structure) is acceptable.
+following ticket for possible improvement: #20893
Reviewer: Vincent Delecroix
I moved the part related to improvements to #20893. I definitely think that we should try to have something ready for the next beta release. And it is in good shape!
Changed branch from public/live_documentation_in_jupyter_using_thebe-20690-experimental to u/fcayre/thebe-20690
Description changed:
---
+++
@@ -25,10 +25,13 @@
- [X] Configure the Jupyter notebook in Sage to somehow provide the
server configuration to Thebe (not needed in fact)
-- [/] Preparse or customize/configure Thebe to support Sage's doctest syntax:
- - [ ] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
+- [X] Preparse or customize/configure Thebe to support Sage's doctest syntax:
+ - [X] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
- [X] Strip out the outputs
Bonus: show the included outputs below the cell until the new output is computed
+
+ What's been done here is: output is show until the "activate" button is clicked.
+
- [X] Support doctests with several commands by spliting into several cells
- [X] Check what's the right way for including thebe.js in the Sage
As discussed with Florent (by mail) the first step should be ready (see #20893 for next steps). I am going through the changes and testing this version.
Description changed:
---
+++
@@ -8,7 +8,7 @@
documentation in the Jupyter notebook as we had in the legacy Sage
notebook.
-Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
+Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
@@ -38,4 +38,5 @@
sources. Should we have a spkg? (to be discussed at Sage Days 74
with Volker).
-following ticket for possible improvement: #20893
+Follow-up ticket for possible improvement: #20893.
+This ticket solves #17269.
This ticket solves #17269.
Replying to @slel:
This ticket solves #17269.
Thanks for letting me know about the current ticket. This is indeed a blocker to leave sage notebook for good (this, and the fact that jupyter doen not handle .rst
files as worksheets, let me continue to use the former during tutorials).
With the current version, the button activate
does not appear in all situation. It does for the reference manual but not for Help -> Thematic Tutorials -> Tutorial: Sage Introductory Programming (PREP)
.
Changed reviewer from Vincent Delecroix to Vincent Delecroix, Thierry Monteil
thebe.js
should not be raw copied to Sage source code. Instead, it should be installed as a Sage package, so that it is easier to keep it up-to-date. Typically, the script you copied is adapted to Jupyter 4.0.5.
Hi Thierry,
Thanks for looking at this!
It was Volker's suggestion to just raw copy thebe.js in the sources.
One part of the rationale is simplicity. The other is that, once jupyterlab will have matured out, thebe.js is likely to become a thin layer on top of it, if not just a part of it. So it's not that crucial to take the efforts of a super clean long term solution.
But I don't have a strong opinion either.
Having a dedicated spkg is not such a huge effort, and there are tons of temporary things in Sage that wait to be cleaned for years, let us not make things worse when we can avoid it. Let me just give a try.
Changed branch from u/fcayre/thebe-20690 to u/tmonteil/thebe-20690
Dependencies: #21309
Description changed:
---
+++
@@ -34,9 +34,8 @@
- [X] Support doctests with several commands by spliting into several cells
-- [X] Check what's the right way for including thebe.js in the Sage
- sources. Should we have a spkg? (to be discussed at Sage Days 74
- with Volker).
+- [X] Ship thebe.js from a dedicated spkg (#21309).
Follow-up ticket for possible improvement: #20893.
This ticket solves #17269.
+
I wrote #21309 to package thebe.js (needs review) and let the current branch depend on that one (i.e. i replaced the hardcoded code to a symlink to the file provided by the spkg). It works well on my machine.
New commits:
7d4fe86 | #21309 : package thebejs. |
f508730 | Merge branch 'u/fcayre/thebe-20690' of trac.sagemath.org:sage into t/21309/package_thebe_js |
ef6657d | #20690 : use thebe.js from the thebejs package instead of the hardcoded one. |
Replying to @videlec:
With the current version, the button
activate
does not appear in all situation. It does for the reference manual but not forHelp -> Thematic Tutorials -> Tutorial: Sage Introductory Programming (PREP)
.
I double checked this. Actually, the button does not appear when the pages do not have cells (the first pages of the PREP are just pictures, no computations), but it does otherwise (see e.g. the "Calculus 1" page), so it is somehow a good feature.
Replying to @sagetrac-tmonteil:
I wrote #21309 to package thebe.js (needs review) and let the current branch depend on that one (i.e. i replaced the hardcoded code to a symlink to the file provided by the spkg). It works well on my machine.
Ça c'est gentil!
For the record, I had Florent Cayré on the phone this morning. He started looking at this, but somehow he has a technical issue posting messages on trac which we did not manage to debug. Anyway, we should be able to review this shortly (e.g. tomorrow during the Sage Days).
Changed keywords from days77, jupyter, thebe, notebook to days77, jupyter, thebe, notebook, sd75
Great ! (i just arrived at Cernay, barbecue tonight!)
Changed branch from u/tmonteil/thebe-20690 to u/nthiery/thebe-20690
Branch pushed to git repo; I updated commit sha1. New commits:
4278753 | 20690: Added comment about Thebe and Sage's thebejs package |
Description changed:
---
+++
@@ -8,34 +8,36 @@
documentation in the Jupyter notebook as we had in the legacy Sage
notebook.
-Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
+Kudos to Rob Beezer for pointing us to Thebe in his presentation of
+MathBookXML at Sage Days 77.
Steps:
- [X] Configure Sphinx to add the Thebe javascript library in the static page
- [X] Configure Sphinx to add a small header to our html page with:
- [X] Inclusion of the Thebe javascript
- [X] Thebe configuration: which divs to make live
- Currently, we include all <pre> tags that contain the "sage:" prompt
- TODO: shall we change to <pre> tags that start with the "sage:" prompt ?
-to do?
+
+ Currently, we include all <pre> tags that contain the "sage:" prompt.
+
+ TODO: shall we change to <pre> tags that start with the "sage:" prompt?
+
+TODO:
- [X] Only activate Thebe if the page is served by a Jupyter instance
- Currently we check that the protocol is http
+
+ Currently we check that the protocol is http
- [X] A button to activate live cells
-
- [X] Configure the Jupyter notebook in Sage to somehow provide the
- server configuration to Thebe (not needed in fact)
-
+ server configuration to Thebe (not needed in fact)
- [X] Preparse or customize/configure Thebe to support Sage's doctest syntax:
- [X] Strip out the "sage: " prompts and "....:" and "... " continuation prompts
- [X] Strip out the outputs
- Bonus: show the included outputs below the cell until the new output is computed
- What's been done here is: output is show until the "activate" button is clicked.
+ Bonus: show the included outputs below the cell until the new output is computed
- - [X] Support doctests with several commands by spliting into several cells
+ What's been done here is: output is show until the "activate" button is clicked.
-- [X] Ship thebe.js from a dedicated spkg (#21309).
+- [X] Support doctests with several commands by spliting into several cells
+- [X] Ship Thebe from a dedicated spkg (#21309).
-Follow-up ticket for possible improvement: #20893.
-This ticket solves #17269.
+This ticket solves #17269. Follow-up ticket for possible improvements: #20893.
(Just editing ticket description, fixing formatting.)
Thebe is a Jupyter javascript plugin for static sites that allows for rendering selected divs of the HTML as live cells connected to a Jupyter server:
https://oreillymedia.github.io/thebe/
The goal of this ticket is to use this technology to implement live documentation in the Jupyter notebook as we had in the legacy Sage notebook.
Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
Steps:
[X] Configure Sphinx to add a small header to our html page with:
Currently, we include all
TODO:
[X] Only activate Thebe if the page is served by a Jupyter instance
Currently we check that the protocol is http
[X] A button to activate live cells
[X] Configure the Jupyter notebook in Sage to somehow provide the server configuration to Thebe (not needed in fact)
[X] Preparse or customize/configure Thebe to support Sage's doctest syntax:
Bonus: show the included outputs below the cell until the new output is computed
What's been done here is: output is show until the "activate" button is clicked.
[X] Support doctests with several commands by spliting into several cells
[X] Ship Thebe from a dedicated spkg (#21309).
This ticket solves #17269. Follow-up ticket for possible improvements: #20893.
Depends on #21309
CC: @videlec @vbraun @rbeezer @slel @sagetrac-tmonteil
Component: documentation
Keywords: days77, jupyter, thebe, notebook, sd75
Author: Florent Cayré, Nicolas M. Thiéry
Branch:
8c8e731
Reviewer: Vincent Delecroix, Thierry Monteil
Issue created by migration from https://trac.sagemath.org/ticket/20690