#20690: Live documentation in Jupyter using Thebe
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: new
Priority: major | Milestone: sage-7.3
Component: documentation | Resolution:
Keywords: days77, jupyter, | Merged in:
thebe, notebook |
Authors: Florent Cayré, | Reviewers: Vincent Delecroix
Nicolas M. Thiéry |
Report Upstream: N/A | Work issues:
Branch: | Commit:
public/live_documentation_in_jupyter_using_thebe-20690-experimental|
07035fd4b6db42b55131c19026f274e4e624f33b
Dependencies: | Stopgaps:
-------------------------------------+-------------------------------------
Changes (by vdelecroix):
* reviewer: => Vincent Delecroix
Old description:
> 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
>
> - 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.
New description:
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
--
--
Ticket URL: <https://trac.sagemath.org/ticket/20690#comment:17>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
