sagemath / sage

Main repository of SageMath
https://www.sagemath.org
Other
1.42k stars 477 forks source link

Live documentation in Jupyter using Thebe #20690

Closed nthiery closed 8 years ago

nthiery commented 8 years ago

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.

Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.

Steps:

TODO:

This ticket solves #17269. Follow-up ticket for possible improvements: #20893.

Depends on #21309

CC: @videlec @vbraun @rbeezer @slel @sagetrac-tmonteil

Component: documentation

Keywords: days77, jupyter, thebe, notebook, sd75

Author: Florent Cayré, Nicolas M. Thiéry

Branch: 8c8e731

Reviewer: Vincent Delecroix, Thierry Monteil

Issue created by migration from https://trac.sagemath.org/ticket/20690

nthiery commented 8 years ago

Branch: u/nthiery/live_documentation_in_jupyter_using_thebe

nthiery commented 8 years ago

Changed branch from u/nthiery/live_documentation_in_jupyter_using_thebe to public/live_documentation_in_jupyter_using_thebe-20690

nthiery commented 8 years ago

Commit: 19f31f8

nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -1 +1,18 @@
+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:
+- Configure Sphinx to add the Thebe javascript library in the static page
+- Configure Sphinx to add a small header to our html page with:
+  - Inclusion of the Thebe javascript
+  - Thebe configuration: which divs to make live, which server to use
+  - A button to turn on 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)
+  - Bonus: support doctests with several commands by split into several cells 
nthiery commented 8 years ago

New commits:

19f31f820690: added some examples of sage code in a fast-to-compile document. DONT MERGE IN SAGE
nthiery commented 8 years ago

Changed branch from public/live_documentation_in_jupyter_using_thebe-20690 to public/live_documentation_in_jupyter_using_thebe-20690-experimental

nthiery commented 8 years ago

Changed branch from public/live_documentation_in_jupyter_using_thebe-20690-experimental to public/live_documentation_in_jupyter_using_thebe-20690

nthiery commented 8 years ago
comment:5

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!).

nthiery commented 8 years ago

Changed branch from public/live_documentation_in_jupyter_using_thebe-20690 to public/live_documentation_in_jupyter_using_thebe-20690-experimental

nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -5,14 +5,14 @@
 The idea is to use this technology to make

 Steps:
-- Configure Sphinx to add the Thebe javascript library in the static page
-- Configure Sphinx to add a small header to our html page with:
-  - Inclusion of the Thebe javascript
-  - Thebe configuration: which divs to make live, which server to use
-  - A button to turn on 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.
+- [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
+  - [ ] Thebe configuration: which divs to make live, which server to use
+  - [ ] 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)
-  - Bonus: support doctests with several commands by split into several cells 
+  - [ ] 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 split into several cells 
nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -6,13 +6,18 @@

 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:
+- [ / ] Configure Sphinx to add a small header to our html page with:
   - [X] Inclusion of the Thebe javascript
-  - [ ] Thebe configuration: which divs to make live, which server to use
-  - [ ] A button to activate live cells
+  - [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 split into several cells 
+  - [ ] Support doctests with several commands by spliting into several cells
+
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

5016cd820690: First implementation of a live documentation in Jupyter using Thebe
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Changed commit from 19f31f8 to 5016cd8

nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -1,23 +1,82 @@
-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:
+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
+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 sage:
+        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 use window.location.origin; is this the right thing to do?
-  - [ ] Only activate Thebe if running inside a Jupyter server
+        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
-  - [ ] 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)
+
+- [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.
+
nthiery commented 8 years ago

Changed keywords from none to days77, jupyter, thebe, notebook

nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -7,6 +7,8 @@
 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.
+
+Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML.

 Steps:
 - [X] Configure Sphinx to add the Thebe javascript library in the static page
nthiery commented 8 years ago

Description changed:

--- 
+++ 
@@ -8,7 +8,7 @@
 documentation in the Jupyter notebook as we had in the legacy Sage
 notebook.

-Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML.
+Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.

 Steps:
 - [X] Configure Sphinx to add the Thebe javascript library in the static page
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

32c9e6420690: Only show the activate button when there are cells to be activated
d6aaed220690: Disable the activate button once clicked
b5e95e420690: Factor out a thebe-sage setup function before complexifying it for upcoming functionalities
07035fd20690: On live doc activation, hide expected results and add a Run button before them
7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Changed commit from 5016cd8 to 07035fd

videlec commented 8 years ago
comment:15

Everything seems to work (nice!). Some naive questions from a user point of view:

Less importantly:

videlec commented 8 years ago

Description changed:

--- 
+++ 
@@ -12,31 +12,32 @@

 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] 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
+  - [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
+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
+  - [X] 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
+  - [X] 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:
+
+- [  ] 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
@@ -53,7 +54,7 @@

 - [ ] 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
+      `-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"

@@ -81,4 +82,3 @@
 - [ ] Add support in Thebe for basic export to Jupyter notebooks. A
       quality loss (in particular in terms of the hierarchical
       structure) is acceptable.
-
videlec commented 8 years ago

Description changed:

--- 
+++ 
@@ -25,60 +25,14 @@
 - [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:
+- [/] Preparse or customize/configure Thebe to support Sage's doctest syntax:
   - [ ] Strip out the "sage: " prompts and "....:" and "...  " continuation prompts
   - [X] Strip out the outputs
         Bonus: show the included outputs below the cell until the new output is computed
   - [X] Support doctests with several commands by spliting into several cells

-- Check what's the right way for including thebe.js in the Sage
+- [X] 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:
-
-- [  ] 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.
+following ticket for possible improvement: #20893
videlec commented 8 years ago

Reviewer: Vincent Delecroix

videlec commented 8 years ago
comment:18

I moved the part related to improvements to #20893. I definitely think that we should try to have something ready for the next beta release. And it is in good shape!

0d4aac26-9630-439d-8a55-24f4aa936131 commented 8 years ago

Changed branch from public/live_documentation_in_jupyter_using_thebe-20690-experimental to u/fcayre/thebe-20690

0d4aac26-9630-439d-8a55-24f4aa936131 commented 8 years ago

Changed commit from 07035fd to 5f9fc0e

0d4aac26-9630-439d-8a55-24f4aa936131 commented 8 years ago

Description changed:

--- 
+++ 
@@ -25,10 +25,13 @@
 - [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
+- [X] Preparse or customize/configure Thebe to support Sage's doctest syntax:
+  - [X] Strip out the "sage: " prompts and "....:" and "...  " continuation prompts
   - [X] Strip out the outputs
         Bonus: show the included outputs below the cell until the new output is computed
+
+        What's been done here is: output is show until the "activate" button is clicked.
+
   - [X] Support doctests with several commands by spliting into several cells

 - [X] Check what's the right way for including thebe.js in the Sage
videlec commented 8 years ago
comment:20

As discussed with Florent (by mail) the first step should be ready (see #20893 for next steps). I am going through the changes and testing this version.

slel commented 8 years ago

Description changed:

--- 
+++ 
@@ -8,7 +8,7 @@
 documentation in the Jupyter notebook as we had in the legacy Sage
 notebook.

-Kuddos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
+Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.

 Steps:
 - [X] Configure Sphinx to add the Thebe javascript library in the static page
@@ -38,4 +38,5 @@
   sources. Should we have a spkg? (to be discussed at Sage Days 74
   with Volker).

-following ticket for possible improvement: #20893
+Follow-up ticket for possible improvement: #20893.
+This ticket solves #17269.
slel commented 8 years ago
comment:21

This ticket solves #17269.

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:22

Replying to @slel:

This ticket solves #17269.

Thanks for letting me know about the current ticket. This is indeed a blocker to leave sage notebook for good (this, and the fact that jupyter doen not handle .rst files as worksheets, let me continue to use the former during tutorials).

videlec commented 8 years ago
comment:23

With the current version, the button activate does not appear in all situation. It does for the reference manual but not for Help -> Thematic Tutorials -> Tutorial: Sage Introductory Programming (PREP).

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Changed reviewer from Vincent Delecroix to Vincent Delecroix, Thierry Monteil

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:24

thebe.js should not be raw copied to Sage source code. Instead, it should be installed as a Sage package, so that it is easier to keep it up-to-date. Typically, the script you copied is adapted to Jupyter 4.0.5.

nthiery commented 8 years ago
comment:25

Hi Thierry,

Thanks for looking at this!

It was Volker's suggestion to just raw copy thebe.js in the sources.

One part of the rationale is simplicity. The other is that, once jupyterlab will have matured out, thebe.js is likely to become a thin layer on top of it, if not just a part of it. So it's not that crucial to take the efforts of a super clean long term solution.

But I don't have a strong opinion either.

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:26

Having a dedicated spkg is not such a huge effort, and there are tons of temporary things in Sage that wait to be cleaned for years, let us not make things worse when we can avoid it. Let me just give a try.

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Changed branch from u/fcayre/thebe-20690 to u/tmonteil/thebe-20690

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Dependencies: #21309

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Changed commit from 5f9fc0e to ef6657d

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Description changed:

--- 
+++ 
@@ -34,9 +34,8 @@

   - [X] Support doctests with several commands by spliting into several cells

-- [X] 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).
+- [X] Ship thebe.js from a dedicated spkg (#21309).

 Follow-up ticket for possible improvement: #20893.
 This ticket solves #17269.
+
edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:28

I wrote #21309 to package thebe.js (needs review) and let the current branch depend on that one (i.e. i replaced the hardcoded code to a symlink to the file provided by the spkg). It works well on my machine.


New commits:

7d4fe86#21309 : package thebejs.
f508730Merge branch 'u/fcayre/thebe-20690' of trac.sagemath.org:sage into t/21309/package_thebe_js
ef6657d#20690 : use thebe.js from the thebejs package instead of the hardcoded one.
edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:29

Replying to @videlec:

With the current version, the button activate does not appear in all situation. It does for the reference manual but not for Help -> Thematic Tutorials -> Tutorial: Sage Introductory Programming (PREP).

I double checked this. Actually, the button does not appear when the pages do not have cells (the first pages of the PREP are just pictures, no computations), but it does otherwise (see e.g. the "Calculus 1" page), so it is somehow a good feature.

nthiery commented 8 years ago
comment:30

Replying to @sagetrac-tmonteil:

I wrote #21309 to package thebe.js (needs review) and let the current branch depend on that one (i.e. i replaced the hardcoded code to a symlink to the file provided by the spkg). It works well on my machine.

Ça c'est gentil!

For the record, I had Florent Cayré on the phone this morning. He started looking at this, but somehow he has a technical issue posting messages on trac which we did not manage to debug. Anyway, we should be able to review this shortly (e.g. tomorrow during the Sage Days).

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago

Changed keywords from days77, jupyter, thebe, notebook to days77, jupyter, thebe, notebook, sd75

edd8e884-f507-429a-b577-5d554626c0fe commented 8 years ago
comment:31

Great ! (i just arrived at Cernay, barbecue tonight!)

nthiery commented 8 years ago

Changed branch from u/tmonteil/thebe-20690 to u/nthiery/thebe-20690

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Changed commit from ef6657d to 4278753

7ed8c4ca-6d56-4ae9-953a-41e42b4ed313 commented 8 years ago

Branch pushed to git repo; I updated commit sha1. New commits:

427875320690: Added comment about Thebe and Sage's thebejs package
slel commented 8 years ago

Description changed:

--- 
+++ 
@@ -8,34 +8,36 @@
 documentation in the Jupyter notebook as we had in the legacy Sage
 notebook.

-Kudos to Rob Beezer for pointing us to Thebe in his presentation of MathBookXML at Sage Days 77.
+Kudos to Rob Beezer for pointing us to Thebe in his presentation of
+MathBookXML at Sage Days 77.

 Steps:
 - [X] Configure Sphinx to add the Thebe javascript library in the static page
 - [X] 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 ?
-to do?
+
+    Currently, we include all <pre> tags that contain the "sage:" prompt.
+
+    TODO: shall we change to <pre> tags that start with the "sage:" prompt?
+
+TODO:
 - [X] Only activate Thebe if the page is served by a Jupyter instance
-      Currently we check that the protocol is http
+
+  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)
-
+  server configuration to Thebe (not needed in fact)
 - [X] Preparse or customize/configure Thebe to support Sage's doctest syntax:
   - [X] Strip out the "sage: " prompts and "....:" and "...  " continuation prompts
   - [X] Strip out the outputs
-        Bonus: show the included outputs below the cell until the new output is computed

-        What's been done here is: output is show until the "activate" button is clicked.
+    Bonus: show the included outputs below the cell until the new output is computed

-  - [X] Support doctests with several commands by spliting into several cells
+    What's been done here is: output is show until the "activate" button is clicked.

-- [X] Ship thebe.js from a dedicated spkg (#21309).
+- [X] Support doctests with several commands by spliting into several cells
+- [X] Ship Thebe from a dedicated spkg (#21309).

-Follow-up ticket for possible improvement: #20893.
-This ticket solves #17269.
+This ticket solves #17269. Follow-up ticket for possible improvements: #20893.
slel commented 8 years ago
comment:34

(Just editing ticket description, fixing formatting.)