Opened 3 years ago
Last modified 3 years ago
#20690 closed enhancement
Live documentation in Jupyter using Thebe — at Version 21
Reported by:  nthiery  Owned by:  

Priority:  major  Milestone:  sage7.4 
Component:  documentation  Keywords:  days77, jupyter, thebe, notebook, sd75 
Cc:  vdelecroix, vbraun, rbeezer, slelievre, tmonteil  Merged in:  
Authors:  Florent Cayré, Nicolas M. Thiéry  Reviewers:  Vincent Delecroix 
Report Upstream:  N/A  Work issues:  
Branch:  u/fcayre/thebe20690 (Commits)  Commit:  5f9fc0e62bfe1c37f6a3419e9170ef0159f615f8 
Dependencies:  Stopgaps: 
Description (last modified by )
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:
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 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?
 [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:
 [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 sources. Should we have a spkg? (to be discussed at Sage Days 74 with Volker).
Followup ticket for possible improvement: #20893. This ticket solves #17269.
Change History (21)
comment:1 Changed 3 years ago by
 Branch set to u/nthiery/live_documentation_in_jupyter_using_thebe
comment:2 Changed 3 years ago by
 Branch changed from u/nthiery/live_documentation_in_jupyter_using_thebe to public/live_documentation_in_jupyter_using_thebe20690
comment:3 Changed 3 years ago by
 Commit set to 19f31f8567ac77094d2ee483e7adf9d6963a8dd7
 Description modified (diff)
 Summary changed from Live documentation in Jupyter using thebe to Live documentation in Jupyter using Thebe
comment:4 Changed 3 years ago by
 Branch changed from public/live_documentation_in_jupyter_using_thebe20690 to public/live_documentation_in_jupyter_using_thebe20690experimental
comment:5 Changed 3 years ago by
 Branch changed from public/live_documentation_in_jupyter_using_thebe20690experimental to public/live_documentation_in_jupyter_using_thebe20690
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!).
comment:6 Changed 3 years ago by
 Branch changed from public/live_documentation_in_jupyter_using_thebe20690 to public/live_documentation_in_jupyter_using_thebe20690experimental
comment:7 Changed 3 years ago by
 Description modified (diff)
comment:8 Changed 3 years ago by
 Description modified (diff)
comment:9 Changed 3 years ago by
 Commit changed from 19f31f8567ac77094d2ee483e7adf9d6963a8dd7 to 5016cd83634381cd6be0f42154ea759744a7b272
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

comment:10 Changed 3 years ago by
 Description modified (diff)
comment:11 Changed 3 years ago by
 Cc vdelecroix vbraun added
comment:12 Changed 3 years ago by
 Cc rbeezer added
 Description modified (diff)
 Keywords days77 jupyter thebe notebook added
comment:13 Changed 3 years ago by
 Description modified (diff)
comment:14 Changed 3 years ago by
 Commit changed from 5016cd83634381cd6be0f42154ea759744a7b272 to 07035fd4b6db42b55131c19026f274e4e624f33b
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 thebesage setup function before complexifying it for upcoming functionalities

07035fd  20690: On live doc activation, hide expected results and add a Run button before them

comment:15 Changed 3 years ago by
Everything seems to work (nice!). Some naive questions from a user point of view:
 would it be possible to remove the "sage: " string in the cells? It would be convenient since it perturb the editor. It would even be worse with the continuation "....:" since these are not ignored by the sage preparser...
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).
comment:16 Changed 3 years ago by
 Description modified (diff)
comment:17 Changed 3 years ago by
 Description modified (diff)
 Reviewers set to Vincent Delecroix
comment:18 Changed 3 years ago by
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!
comment:19 Changed 3 years ago by
 Branch changed from public/live_documentation_in_jupyter_using_thebe20690experimental to u/fcayre/thebe20690
 Commit changed from 07035fd4b6db42b55131c19026f274e4e624f33b to 5f9fc0e62bfe1c37f6a3419e9170ef0159f615f8
 Description modified (diff)
comment:20 Changed 3 years ago by
 Status changed from new to needs_review
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.
comment:21 Changed 3 years ago by
 Cc slelievre tmonteil added
 Description modified (diff)
This ticket solves #17269.
New commits:
20690: added some examples of sage code in a fasttocompile document. DONT MERGE IN SAGE