Opened 4 years ago
Last modified 3 years ago
#20690 closed enhancement
Live documentation in Jupyter using Thebe — at Version 10
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: | |
Report Upstream: | N/A | Work issues: | |
Branch: | public/live_documentation_in_jupyter_using_thebe-20690-experimental | Commit: | 5016cd83634381cd6be0f42154ea759744a7b272 |
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.
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.
Change History (10)
comment:1 Changed 4 years ago by
- Branch set to u/nthiery/live_documentation_in_jupyter_using_thebe
comment:2 Changed 4 years ago by
- 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
- 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 4 years ago by
- 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
- 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
- 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
- Description modified (diff)
comment:8 Changed 4 years ago by
- Description modified (diff)
comment:9 Changed 4 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 4 years ago by
- Description modified (diff)
New commits:
20690: added some examples of sage code in a fast-to-compile document. DONT MERGE IN SAGE