#20893: improving live documentation in the Jupyter notebook
------------------------------+-----------------------------
Reporter: vdelecroix | Type: enhancement
Status: new | Priority: major
Milestone: sage-7.3 | Component: documentation
Keywords: | Merged in:
Authors: | Reviewers:
Report Upstream: N/A | Work issues:
Branch: | Commit:
Dependencies: #20690 | Stopgaps:
------------------------------+-----------------------------
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.
--
Ticket URL: <https://trac.sagemath.org/ticket/20893>
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.
