Opened 4 years ago

Last modified 3 years ago

#20690 closed enhancement

Live documentation in Jupyter using Thebe — at Version 17

Reported by: nthiery Owned by:
Priority: major Milestone: sage-7.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: public/live_documentation_in_jupyter_using_thebe-20690-experimental Commit: 07035fd4b6db42b55131c19026f274e4e624f33b
Dependencies: Stopgaps:

Description (last modified by vdelecroix)

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.

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
  • [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)

  • / 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
  • [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).

following ticket for possible improvement: #20893

Change History (17)

comment:1 Changed 4 years ago by nthiery

  • Branch set to u/nthiery/live_documentation_in_jupyter_using_thebe

comment:2 Changed 4 years ago by nthiery

  • Branch changed from u/nthiery/live_documentation_in_jupyter_using_thebe to public/live_documentation_in_jupyter_using_thebe-20690

comment:3 Changed 4 years ago by nthiery

  • Commit set to 19f31f8567ac77094d2ee483e7adf9d6963a8dd7
  • Description modified (diff)
  • Summary changed from Live documentation in Jupyter using thebe to Live documentation in Jupyter using Thebe

New commits:

19f31f820690: added some examples of sage code in a fast-to-compile document. DONT MERGE IN SAGE

comment:4 Changed 4 years ago by nthiery

  • Branch changed from public/live_documentation_in_jupyter_using_thebe-20690 to public/live_documentation_in_jupyter_using_thebe-20690-experimental

comment:5 Changed 4 years ago by nthiery

  • Branch changed from public/live_documentation_in_jupyter_using_thebe-20690-experimental to public/live_documentation_in_jupyter_using_thebe-20690

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 4 years ago by nthiery

  • Branch changed from public/live_documentation_in_jupyter_using_thebe-20690 to public/live_documentation_in_jupyter_using_thebe-20690-experimental

comment:7 Changed 4 years ago by nthiery

  • Description modified (diff)

comment:8 Changed 4 years ago by nthiery

  • Description modified (diff)

comment:9 Changed 4 years ago by git

  • Commit changed from 19f31f8567ac77094d2ee483e7adf9d6963a8dd7 to 5016cd83634381cd6be0f42154ea759744a7b272

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

5016cd820690: First implementation of a live documentation in Jupyter using Thebe

comment:10 Changed 4 years ago by nthiery

  • Description modified (diff)

comment:11 Changed 4 years ago by nthiery

  • Cc vdelecroix vbraun added

comment:12 Changed 4 years ago by nthiery

  • Cc rbeezer added
  • Description modified (diff)
  • Keywords days77 jupyter thebe notebook added

comment:13 Changed 4 years ago by nthiery

  • Description modified (diff)

comment:14 Changed 3 years ago by git

  • Commit changed from 5016cd83634381cd6be0f42154ea759744a7b272 to 07035fd4b6db42b55131c19026f274e4e624f33b

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

32c9e6420690: Only show the activate button when there are cells to be activated
d6aaed220690: Disable the activate button once clicked
b5e95e420690: Factor out a thebe-sage setup function before complexifying it for upcoming functionalities
07035fd20690: On live doc activation, hide expected results and add a Run button before them

comment:15 Changed 3 years ago by vdelecroix

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 vdelecroix

  • Description modified (diff)

comment:17 Changed 3 years ago by vdelecroix

  • Description modified (diff)
  • Reviewers set to Vincent Delecroix
Note: See TracTickets for help on using tickets.