Opened 5 years ago

Last modified 4 months ago

#20893 new enhancement

improving live documentation in the Jupyter notebook — at Initial Version

Reported by: vdelecroix Owned by:
Priority: major Milestone: sage-9.3
Component: documentation Keywords: thebe, thebelab
Cc: vbraun, rbeezer, nthiery, fhivert, slelievre, fcayre, jdemeyer, dimpase Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #20690 Stopgaps:

Status badges


Since #20690 we have access to documentation (with live execution) within the Jupyter notebook. It was decided to keep the code simple. There are two ongoing projects within Jupyter for having this working. It might be wiser to wait for them...

Some of the improvements mentioned in #20690 were:

  • [ ] 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.

Change History (0)

Note: See TracTickets for help on using tickets.