Opened 3 years ago

Last modified 15 months ago

#20893 new enhancement

Improve live documentation in the Jupyter notebook

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

Description (last modified by nthiery)

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; there are ongoing discussions for providing an alternative sage-enabled tmpnb)
    • 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"}
    }
    
  • [ ] Have Thebe provide good TAB-completion.
  • [ ] Let the cursor switch to the next cell after evaluation (SHIFT+ENTER).
  • [ ] Extract support for Thebe as a Sphinx extension with (see the related sage-cell extension):
    • [ ] 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.
  • [ ] Allow to save the current state of the webpage as a .ipynb worksheet, to be able to continue working on it later, see this comment.

Change History (17)

comment:1 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:2 Changed 3 years ago by tmonteil

  • Description modified (diff)

comment:3 Changed 3 years ago by slelievre

  • Cc slelievre added
  • Description modified (diff)
  • Summary changed from improving live documentation in the Jupyter notebook to Improve live documentation in the Jupyter notebook

Fix formatting in ticket description.

Regarding "There are two ongoing projects within Jupyter for having this working", would someone add links?

Last edited 3 years ago by slelievre (previous) (diff)

comment:4 Changed 3 years ago by slelievre

  • Description modified (diff)

Editing ticket description to add link to tmpnb issue 203: "Octave kernel and SageMath kernel".

comment:5 Changed 3 years ago by tmonteil

  • Description modified (diff)

comment:6 Changed 3 years ago by tmonteil

  • Description modified (diff)

comment:7 Changed 3 years ago by nthiery

  • Cc fcayre added

comment:8 Changed 2 years ago by kcrisman

  • Cc jdemeyer added

comment:9 Changed 2 years ago by nthiery

  • Description modified (diff)

comment:10 Changed 2 years ago by nthiery

  • Description modified (diff)

comment:11 follow-up: Changed 2 years ago by nthiery

Update: Min RK reported to me that he had started reimplementing Thebe on top of JupyterLab?. At this stage, this seemed to confirm our hope that Thebe will become just a thin layer on top of plain JupyterLab?, making it sustainable.

comment:12 Changed 2 years ago by nthiery

  • Description modified (diff)

comment:13 Changed 2 years ago by nthiery

  • Description modified (diff)

comment:14 Changed 2 years ago by nthiery

A source of inspiration: sympylive.

comment:15 in reply to: ↑ 11 ; follow-up: Changed 2 years ago by tmonteil

Replying to nthiery:

Update: Min RK reported to me that he had started reimplementing Thebe on top of JupyterLab?. At this stage, this seemed to confirm our hope that Thebe will become just a thin layer on top of plain JupyterLab?, making it sustainable.

Is an export to a standalone .ipynb file part of the plan (so that people can save their work on some live doc) ?

comment:16 in reply to: ↑ 15 Changed 2 years ago by nthiery

Replying to tmonteil:

Is an export to a standalone .ipynb file part of the plan (so that people can save their work on some live doc) ?

Ah, shoot, I forgot to discuss this specific point.

That being said, Thebe is meant to be embedded in any web page. So, at the level of Thebe itself, and without a minimum of structure specified, I believe it would be hard to define a meaningful export to .ipynb.

Plausibly we would instead be shooting for a link "download document as ipynb" pointing to the notebook generated from the original sources, either statically or on the fly. The inconvenient being of course that users won't keep their history in this scenario if they play with Thebe before switching to the notebook.

comment:17 Changed 15 months ago by nthiery

  • Description modified (diff)
  • Keywords thebe thebelab added
Note: See TracTickets for help on using tickets.