#20690: Live documentation in Jupyter using Thebe
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: new
Priority: major | Milestone: sage-7.3
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: Florent Cayré, | Reviewers:
Nicolas M. Thiéry | Work issues:
Report Upstream: N/A | Commit:
Branch: | 5016cd83634381cd6be0f42154ea759744a7b272
public/live_documentation_in_jupyter_using_thebe-20690-experimental|
Stopgaps:
Dependencies: |
-------------------------------------+-------------------------------------
Description changed by nthiery:
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 idea is to use this technology to make
>
> 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:
> - [ ] 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 spliting into several
> cells
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.
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 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
- [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.
--
--
Ticket URL: <http://trac.sagemath.org/ticket/20690#comment:10>
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.
