Opened 4 years ago

Closed 2 years ago

#19974 closed defect (fixed)

document "sage --notebook=jupyter"

Reported by: dimpase Owned by:
Priority: blocker Milestone: sage-8.0
Component: documentation Keywords:
Cc: kcrisman, charpent, jdemeyer, vbraun Merged in:
Authors: Karl-Dieter Crisman Reviewers: Emmanuel Charpentier
Report Upstream: N/A Work issues:
Branch: 95cdd4b (Commits) Commit: 95cdd4b1c483d00c65c7fc7164a08ba10e844b16
Dependencies: Stopgaps:

Description

the subject says it all. The docs are silent on this, the only way to find out is from "sage -h"

Change History (37)

comment:1 follow-up: Changed 4 years ago by jdemeyer

  • Summary changed from document "sage --notebook='jupyter'" to document "sage --notebook=jupyter"

comment:2 in reply to: ↑ 1 Changed 4 years ago by dimpase

Replying to jdemeyer:

right, and also fix what sage -h says, for it puts it as 'jupyter'.

comment:3 Changed 4 years ago by kcrisman

  • Cc kcrisman added

comment:4 Changed 4 years ago by charpent

IM(NS)HO, the Jupyter notebook deserves a chapter in the "Reference Manual"

We have currently a "User interface" part, that contains a "Command Line Interface (REPL)" chapter and a "Web Notebook" chapter. The latter should be renamed "The Sage Web notebook (maintainance only)" and a new chapter such as "Sage in the Jupyter notebook" (or maybe "The Sage (extended) Jupyter Notebook") should be added.

We should also document (where ?) how the Sage kernel can be added to an existing Jupyter installation.

We may also do the courtesy to point to SMC as an alternative way to use Sage.

What do you think ?

comment:5 Changed 4 years ago by jdemeyer

There is nothing wrong with ./sage --notebook='jupyter' or even ./sage -"-no"tebo'ok=jup'yter but I find it easier without the quotes.

comment:6 Changed 4 years ago by charpent

  • Cc charpent added

comment:7 Changed 4 years ago by slelievre

We should also document that the simpler sage -n jupyter works too.

comment:8 follow-up: Changed 2 years ago by kcrisman

Is this still valid? I don't know the answer to this.

comment:9 in reply to: ↑ 8 Changed 2 years ago by charpent

Sorry for the late answer. This one deserved a bit of research (in a somewhat crowded timetable...).

Replying to kcrisman:

Is this still valid? I don't know the answer to this.

Yep.

I took the (possible) attitude of a cursory user interested by Sagemath, but not having installed it. The Google search "Sagemath documentation" pointed me to the main documentation page of our main site.

Here I'm pointed to :

In short, nothing ever documents the Jupyter notebook.

As of 7.6rc0 (what I have on my current machine), the local documentation (as seen in the Jupyter notebook "Help" item) is in the same state...

I do not know how much of the (quite valuable) information on the old notebook use, tips and tricks is still valid for the Jupyter notebook. For example, I found, by trial and error, that the debugger can be used in Jupyter cells. This is not documented.

If we want to make Jupyter our default notebook, this is, to say the least, a bit short... At the very minimum :

  • the "Tutorial pages should be revised to reflect what is obtained in the Jupyter notebook,
  • the old notebook documentation should be edited to mention that this refers to an (outdated|deprecated) interface,
  • a big fat pointer to a Jupyter tutorial should be given, and
  • a new (and short !) "Introduction to Sage" using the Jupyter notebook as a basic interface should be created.

Not a small task.

I can help, but I'm relatively ignorant of the respective possibilities of the old and the Jupyter notebooks ; someone knowing well those two interfaces should manage the work. Pssibly those people who have written them ;-)...

We could also add a cherry to this (already loaded) pie and try to document (briefly) the specifics of the IPython interface...

comment:10 follow-up: Changed 2 years ago by kcrisman

  • Milestone changed from sage-7.1 to sage-8.0
  • Priority changed from critical to blocker

Sounds like a blocker to me to update documentation enough for people to actually get help!

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

Replying to kcrisman:

Sounds like a blocker to me to update documentation enough for people to actually get help!

To be precise, it's a blocker for making Jupyter the default notebook. It should not block further releases of Sagemath, as long as the old notebook remains the default.

We are in a bit of contradiction here : most people "actively" using Sage (i. e. reporting problems with it, and sometimes making a nuisance of themselves) are "old hands", and usually developers (indeed, IIRC, one has to have access to trac (i. e. valid user ID and password) to be able to file a ticket).

So "obvious" failures such as failing to document our default GUI tend to be overlooked (see below)...

I propose to change the title of this ticket to "Document the Jupyter notebook", making it a task, and refer other tickets related to this documentation work to the present ticket.

side note

BTW : the only way open to "lay users" to report a bug is to complain on sage-support, with variable levels of answers (I confess that I am not very big on this particular list : other developers do an admirable work of tending troubled users...). Similarly, I do not know what scanning (if any) is made on "Ask Sagemath".

It might be worthy to setup a system for letting end-users formally report bugs, i. e. some kind of queue where identified issues of identified people could be recorded and formally answered by either a) pointing the user to the solution or b)= filing a ticket if it is indeed a bug.

But I'm not sure that such a formal system would work better than our current informal scanning of sage-support.

Is this worthy of discussion on sage-devel ?

comment:12 Changed 2 years ago by kcrisman

As to the side note, in the past we had a Google doc spreadsheet which some of us would very occasionally try to get stuff off of (it still exists, don't ask me for the link right this second). But no one really looked at it. A big problem is that Sage has precisely zero people dedicated only to support (I mean Sage proper, not SMC). There are many people who help on support, but no master strategy.

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

Replying to charpent:

Replying to kcrisman:

Sounds like a blocker to me to update documentation enough for people to actually get help!

To be precise, it's a blocker for making Jupyter the default notebook. It should not block further releases of Sagemath, as long as the old notebook remains the default.

Well, I believe 8.0 is indeed set to make Jupyter default, right? With #22821 and #23066 this is the last remaining notebook-related blocker for 8.0.

(There are others related to passing of tests and Cygwin, which are also important goals, but that is not something we can address here!)

comment:14 in reply to: ↑ 13 ; follow-up: Changed 2 years ago by jdemeyer

Replying to kcrisman:

Well, I believe 8.0 is indeed set to make Jupyter default, right?

Not really. It would make the SageNB exporter the default.

comment:15 in reply to: ↑ 14 Changed 2 years ago by kcrisman

Well, I believe 8.0 is indeed set to make Jupyter default, right?

Not really. It would make the SageNB exporter the default.

Good point. But nonetheless this would seem to be the time to document this.

comment:16 follow-up: Changed 2 years ago by kcrisman

I have some time the next few days/next week to work on this, but I would like some direction as to exactly what we would like here.

  • First, we would need to update sage -h and sage -advanced at least slightly, probably also the output of sage --notebook --help.
  • There is a lot in comment:9 to add. Given that the initial will be default Export, what do you (any of you) think is necessary for 8.0?
  • Updating old documentation might be a bit trickier. At least adding some brief verbiage e.g. in the PREP notes regarding this no longer being the default, but still quite invokable, would be good.

Thoughts?

comment:17 in reply to: ↑ 16 ; follow-up: Changed 2 years ago by charpent

Replying to kcrisman:

I have some time the next few days/next week to work on this, but I would like some direction as to exactly what we would like here.

  • First, we would need to update sage -h and sage -advanced at least slightly, probably also the output of sage --notebook --help.

This is probably the easiest task ... one one knows where these messages have their sources...

  • There is a lot in comment:9 to add. Given that the initial will be default Export,

I'm not sure to understand what you mean by that...

what do you (any of you) think is necessary for 8.0?

Again from the persective of a total beginner :

  • this section of the tutorial (which, BTW, does not seem to be up to date for the current state of the Sage notebook), should be prefaced by pointing that this is the behaviopur of the OLD notebook ; a similar schema (coming first ?) should document the architecture of the Jupyter notebook.
  • The first part of the "Notebook" section of thematic tutorial, which explains how to create an account on a Sage server and loggin in, is irrelevant to the Jupyter notebook : it should be edited to point that out.

The second part (creating a new worksheet, acessing the tutorial and the online help) must be replaced.

A similar page, such as "Starting the Jupyter notebook", should show (including screenshots ?) how to start the Jupyter notebook, and emphasizes that this is a local operation (as far as I know, the Jupyter notebook won't serve a request from another machine, and won't serve two or more users : that's a job for Jupyter-Hub..).

A second part should show :

  • how to navigate the filesystem ;
  • how to create a new sheet ;
  • basic use of the worksheet (including %display typeset and at least one plot example, and possibly a plot3d example) ; stay at the high-school/freshman level : more sophisticated examples have their uses in the Sage tutorial, not the Jupyter notebook tutorial ;
  • access to online help, via topic<tab>, topic? in a cell and the help menu
  • a brief explanation on edition in the notebook (incl. renaming a file...) ;
  • pointer to the tutorials, and, last but not least :
  • a big, fat, unmistakable pointer to a (the ?) "general" Jupyter doc.

This is new doc. Unless I'm mistaken, it needs (annotated) screenshots (how can we do that in rst ?). It also needs cross-references from the rest of the doc.

To be discussed : this new doc should probably come before the Sage notebook doc. Should it replace it ? I think so (as long as the old doc remains accessible somewhere and is pointed at as necessary), but I'm not sure of my judgement about this and would be glad to hear what other people think...

  • The notebook chapter of the reference manual has, as far as I know, no equivalent for the Jupyter notebook. This has to be written (probably by the Jupyter notebook author (no good deed stays unpunished ;-))

But this might stay undocumented in 8.0, as long as a placeholder announcing that "the programming info is forthcoming" is inserted at the relevant place(s) : this is advanced user's/developper's info, i. e. people who are able to dive in the source if necessary. In contrast, tutorial and basic information is vital necessity for Sage users and can't wait (IMNSHO...).

  • Updating old documentation might be a bit trickier. At least adding some brief verbiage e.g. in the PREP notes regarding this no longer being the default, but still quite invokable, would be good.

The old doc must be invokable as long as the old notebook is standrd in Sage. If it ever becomes optional, these docs could become part of the optional package...

Thoughts?

That's a lot of work. For which I can't help for about two weeks (my RealLife? (TM) is complicated...).

comment:18 Changed 2 years ago by vbraun

Any progress? If nobody volunteers a patch then I'll have to skip this ticket for 8.0...

comment:19 Changed 2 years ago by vbraun

Any progress? If nobody volunteers a patch then I'll have to skip this ticket for 8.0...

comment:20 in reply to: ↑ 17 Changed 2 years ago by kcrisman

  • First, we would need to update sage -h and sage -advanced at least slightly, probably also the output of sage --notebook --help.

This is probably the easiest task ... one one knows where these messages have their sources...

  • There is a lot in comment:9 to add. Given that the initial will be default Export,

I'm not sure to understand what you mean by that...

Technically the default will be to open a server that offers the opportunity to export sagenb to Jupyter, and/or to choose one or the other (but not as a default, yet).

what do you (any of you) think is necessary for 8.0?

Again from the persective of a total beginner :

  • this section of the tutorial (which, BTW, does not seem to be up to date for the current state of the Sage notebook), should be prefaced by pointing that this is the behaviopur of the OLD notebook ; a similar schema (coming first ?) should document the architecture of the Jupyter notebook.
  • The first part of the "Notebook" section of thematic tutorial, which explains how to create an account on a Sage server and loggin in, is irrelevant to the Jupyter notebook : it should be edited to point that out.

This I can do Monday or Tuesday. Volker, is that early enough for you?

The rest is more than I can confidently do, given that I really don't use Jupyter other than to test absolute minimum functionality.

comment:21 Changed 2 years ago by vbraun

Some time next week would be great...

comment:22 Changed 2 years ago by kcrisman

Note to self: there are six different translations of the file for the notebook...

Also note to self that charpent is right about the very old information about the notebook.

comment:23 Changed 2 years ago by kcrisman

  • Authors set to Karl-Dieter Crisman
  • Branch set to u/kcrisman/sagenblegacy
  • Cc jdemeyer vbraun added
  • Commit set to 76aacee21e97db0aca1f738692cf24c36ba4b9fc

@charpent this should be a start. Volker or Jeroen may wish to check whether I made some stupid sagenb error (or German error).

If this looks more or less okay as a start, I have three remaining tasks:

  1. Find someone to translate at least a portion of

    This section refers to the legacy Sage notebook, or “sagenb”. See the sagenb documentation for full details.

    SageMath is transitioning to using the Jupyter notebook as a default, which has a different structure. The most important difference for users is that individual worksheets in Jupyter are saved on your local system just like any other file, whereas in the Sage notebook the main point of access is in the files described below via the server.

    Legacy SageNB Notebook

    for me in Japanese, Russian, French, and/or Portuguese.
  2. Update the PREP tutorial at least somewhat. I was the main original author of those documents so that won't be very hard. Yes, we can include pictures, though I would only do one of those probably for a start.
  3. Open a new ticket with the secondary material, especially authoring a proper guide for how to start using Jupyter as outlined very nicely above. I don't think that anyone will be writing a complete replacement for all of this yet, and thankfully none of it is really "wrong" in that sense.

Does this sound like a plan? I don't want to work on the PREP thematic tutorial pages until I know that this work is within epsilon.


New commits:

cc032beChange documentation for sage -h slightly
6d0e9afChange English language version for tutorial notebook
b8bf04bCommit German tutorial change for legacy sagenb
d267279Update other tutorials localz for change to sagenb status
76aaceeUpdate reference manual information

comment:24 Changed 2 years ago by chapoton

French translation below:

Cette section concerne l'ancien bloc-note de Sage (“sagenb”). Pour plus de détails, voir la documentation de sagenb.

SageMath est en cours de transition vers l'utilisation par défaut du bloc-note Jupyter, qui a une structure différente. Pour les utilisateurs, la différence majeure est le fait que les feuilles de calcul sont sauvegardées dans le système de fichiers local comme n'importe quel autre fichier, alors que pour l'ancien bloc-note de Sage le principal accès aux feuilles de calcul passait par le serveur comme expliqué ci-dessous.

Ancien bloc-note SageNB

comment:25 Changed 2 years ago by git

  • Commit changed from 76aacee21e97db0aca1f738692cf24c36ba4b9fc to fc4cc3cca72d96ce9d3e6b86c542e7e4b91dbf55

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

fc4cc3cintro for the french legacy sagenb section

comment:26 Changed 2 years ago by kcrisman

Thanks!

Does this sound like a plan? I don't want to work on the PREP thematic tutorial pages until I know that this work is within epsilon.

Any thoughts by anyone on this? I can ask on sage-devel regarding 1. for ru, ja, pt or we can just leave them alone

comment:27 Changed 2 years ago by git

  • Commit changed from fc4cc3cca72d96ce9d3e6b86c542e7e4b91dbf55 to 6bb46f7afdde3205cfa7ded3b91321d3612a370f

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

6bb46f7Significantly update PREP logging on page for Export/Jupyter

comment:28 Changed 2 years ago by kcrisman

  • Status changed from new to needs_review

Ready for initial review. I'm still working on the second intro page which will have some verbiage, but we need feedback at this point. Don't forget that to build the documentation you will need to do

sage --docbuild prep html

A reviewer should build pdf as well to check it looks okay.

comment:29 follow-up: Changed 2 years ago by charpent

I'll have a look tonight (but have first to update my Sage tree...)

There does not seem a goot "easy" tutorial for Jupyter ; I found the official doc to give a good start, but one has to interpolate Sage-specific bits now and then. Probably not really easy for an absolute beginner. Do you have other suggestions ?

comment:30 in reply to: ↑ 29 Changed 2 years ago by kcrisman

There does not seem a goot "easy" tutorial for Jupyter ; I found the official doc to give a good start, but one has to interpolate Sage-specific bits now and then. Probably not really easy for an absolute beginner. Do you have other suggestions ?

No. I put something in my tutorial here (momentarily will update) but it is frustrating. And guess what! Even to DELETE a cell you have to use the menu or a keyboard shortcut! You can't really do anything at all without either clicking on a menu or learning a shortcut. For all SageNB's faults, the original designers had ordinary users in mind, not just scientific computing people who spend all day at the keyboard. I really wish we had the new CoCalc/SMC Jupyter notebook.

comment:31 Changed 2 years ago by git

  • Commit changed from 6bb46f7afdde3205cfa7ded3b91321d3612a370f to d1b4e1b2ceb6c5ba24aac46304093f1a6dab707b

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

d1b4e1bUpdate intro tutorial with Jupyter pics and doc

comment:32 Changed 2 years ago by kcrisman

OKAY THIS IS READY FOR REVIEW


I can probably get to minor things on the weekend, but only very minor. I hope no one needs even more pictures! That might take too much more time. I think I satisfied a fair amount of the requests here and I am pleased enough with it.

I just received a pt translation so I'll add that momentarily, along with some notes about the two different filesystems.


If we need a new ticket for this stuff:

A second part should show : how to navigate the filesystem ; how to create a new sheet ; basic use of the worksheet (including %display typeset and at least one plot example, and possibly a plot3d example) ; stay at the high-school/freshman level : more sophisticated examples have their uses in the Sage tutorial, not the Jupyter notebook tutorial ; access to online help, via topic<tab>, topic? in a cell and the help menu a brief explanation on edition in the notebook (incl. renaming a file...) ; pointer to the tutorials, and, last but not least : a big, fat, unmistakable pointer to a (the ?) "general" Jupyter doc.

then please open that - but don't copy me because I'm no Jupyter expert! :-)

comment:33 Changed 2 years ago by git

  • Commit changed from d1b4e1b2ceb6c5ba24aac46304093f1a6dab707b to 95cdd4b1c483d00c65c7fc7164a08ba10e844b16

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

b018055Update pt translation for Jupyter more
95cdd4bAdd notes regarding filesystem for SageNB/Jupyter

comment:34 follow-up: Changed 2 years ago by charpent

  • Status changed from needs_review to positive_review

1) Sorry for the delay, imputable to unwanted interruptions...

2) This is a lot of work, which went in the right direction. The "absolute beginner" Sage user is now warned consistently about the existence of two notebooks, one of them being no longer developed. (S)he is pointed to a relevant (if somewhat indigestible) documentation ; the few examples given are, IMHO, sufficient to get her/him on the right track.

3) I did not catch any obvious snags or inconsistencies in the new documentation.

4) There does not seem to exist a documented programmatic interface to the Jupyter notebook, similar to the interface to sagenb.notebook. I may have missed it...

I now realize that a real tutorial about the Jupyter notebook and its use with Sage and related software (e. g. R or gap) is necessary. I also realize that this is a large project : as every one ou us who teaches or has teached, I know that writing such a document is hard. Therefore, this is a long term project.

Being an old fart (60), I tend to think that something like the PREP tutorials would be a good example. But I'm not sure that this is true for the current (or recent) cohorts of students, which seem hooked to other forms, such as video tutorials. Your advice would be more than useful.

As it exists, the current documentation is enough to warn the naive beginner. The current gap in tutorial has to be filled somehow, but this is a long-term project.

==>positive_review

I plan to work on a tutorial but :

1) I need to think to "the right form" of this tuetorial.

2) This needs a lot of interaction with potential users of the tutorial.

I'll open a new ticket for this if and when I have something consistent to propose.

Someone more versed in the internals of (our version of) Jupyter should document what can be done from Sage to interact with it.

comment:35 in reply to: ↑ 34 Changed 2 years ago by kcrisman

2) This is a lot of work, which went in the right direction. The "absolute beginner" Sage user is now warned consistently about the existence of two notebooks, one of them being no longer developed. (S)he is pointed to a relevant (if somewhat indigestible) documentation ; the few examples given are, IMHO, sufficient to get her/him on the right track.

Great!

4) There does not seem to exist a documented programmatic interface to the Jupyter notebook, similar to the interface to sagenb.notebook. I may have missed it...

No, I don't even know if there is such a thing.

I now realize that a real tutorial about the Jupyter notebook and its use with Sage and related software (e. g. R or gap) is necessary. I also realize that this is a large project : as every one ou us who teaches or has teached, I know that writing such a document is hard. Therefore, this is a long term project.

Yes.

Being an old fart (60), I tend to think that something like the PREP tutorials would be a good example. But I'm not sure that this is true for the current (or recent) cohorts of students, which seem hooked to other forms, such as video tutorials. Your advice would be more than useful.

I would love to have there be way more GOOD video tutorials but someone has to make them. I've certainly considered it but don't know if my production values would be very high.

Thanks for the review AND for pushing that this really is a blocker, it is appreciated.

comment:36 Changed 2 years ago by vbraun

  • Reviewers set to Emmanuel Charpentier

comment:37 Changed 2 years ago by vbraun

  • Branch changed from u/kcrisman/sagenblegacy to 95cdd4b1c483d00c65c7fc7164a08ba10e844b16
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.