Thematic tutorials: using the notebook, programming python, comprehensions

[nthiery]

This ticket adds three tutorials that have been developped and extensively used during Sage(-Combinat) events:

• Tutorial: Using the Sage notebook, navigating the help system, first exercises
• Tutorial: Programming in Python and Sage
• Tutorial: Comprehensions, Iterators, and Iterables

There is some redundancy with the PREP's tutorial, but that's fine:
the point of views are complementary.

At this occasion, this ticket also refactors the main Thematic
Tutorials page, grouping them by theme, and cross-linking to thematic
tutorials that are already in the Sage sources (combinatorics, padics)
or other documents (PREP).

A preview of the result is available here:

http://combinat.sagemath.org/doc/thematic_tutorials/

It might be slightly outdated w.r.t. the latest version of the
patch. Also one should ignore the SEEALSO section which is added by a
later patch in the Sage-Combinat queue.

CC: @sagetrac-sage-combinat @seblabbe @novoselt @haraldschilly

Component: documentation

Keywords: thematic tutorials

Author: Franco Saliola, Florent Hivert, Nicolas M. Thiéry

Reviewer: Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg

Merged: sage-5.8.beta3

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

[nthiery]

comment:1

Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.

[jhpalmieri]

comment:2

I think that intersphinx linking to the reference manual should be fixed by #6495. See also a sage-support thread.

[jhpalmieri]

comment:3

By the way, was the sandpile document removed from the top-level index file intentionally?

[nthiery]

comment:5

Replying to @jhpalmieri:

By the way, was the sandpile document removed from the top-level index file intentionally?

Ouch, thanks for catching this. The sandpile document should definitely be there. Where would you put it? In the combinatorics section maybe?

Cheers,
Nicolas

[nthiery]

comment:6

Replying to @jhpalmieri:

I think that intersphinx linking to the reference manual should be fixed by #6495. See also a sage-support thread.

That would be excellent news to have this feature back shortly! (not counting on the exciting parallel feature!

                          Nicolas

[seblabbe]

Attachment: Image 27.png

[seblabbe]

comment:9

Replying to @nthiery:

Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.

Yes, I remember vaguely but I can't remember exactly... Maybe, it was a bigger patch no? with more sections? Anyway, I looked at it and I think the sections and their order are fine.

1. However, some links do not appear as links (see attached png).

2. Also, links to PREP tutorials do not work.

[seblabbe]

comment:10

I get the following 16 warning when building the html :

sage -docbuild thematic_tutorials html

....

reading sources... [ 95%] tutorial-objects-and-classes
reading sources... [100%] tutorial-programming-python
                                                                                                
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:390: WARNING: Literal block expected; none found.
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:788: WARNING: image file not readable: media/graph0.png
looking for now-outdated files... none found
pickling environment... done                                                      
checking consistency... /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tut
orials/functional_programming.rst:: WARNING: document isn't included in any toctree             
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/group_theory.rst:
: WARNING: document isn't included in any toctree                                               
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/lie.rst:: WARNING
: document isn't included in any toctree                                                        
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/linear_programmin
g.rst:: WARNING: document isn't included in any toctree                                         
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/numtheory_rsa.rst
:: WARNING: document isn't included in any toctree                                              
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/sandpile.rst:: WA
RNING: document isn't included in any toctree                                                   
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-comprehe
nsions.rst:: WARNING: document isn't included in any toctree                                    
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-notebook
-and-help-long.rst:: WARNING: document isn't included in any toctree                            
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-objects-
and-classes.rst:: WARNING: document isn't included in any toctree                               
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:: WARNING: document isn't included in any toctree

...

writing output... [100%] tutorial-programming-python                                            
                                                                                                
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:52: WAR
NING: undefined label: sage.rings.padics.tutorial (if the link has no caption the label must pre
cede a section header)                                                                          
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:60: WAR
NING: undefined label: sage.combinat.tutorial (if the link has no caption the label must precede
 a section header)                                                                              
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:88: WAR
NING: undefined label: sage.categories.primer (if the link has no caption the label must precede
 a section header)                                                                              
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:89: WAR
NING: undefined label: sage.categories.tutorial (if the link has no caption the label must prece
de a section header)                                                                            
writing additional files... genindex search                                                     
copying images... [  2%] media/sandpile/btw.png

...

build succeeded, 16 warnings.
Build finished.  The built documents can be found in /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/output/html/en/thematic_tutorials

[nthiery]

comment:11

Hi Sébastien!

Replying to @seblabbe:

I get the following 16 warning when building the html:

/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:390: WARNING: Literal block expected; none found.
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programm
ing-python.rst:788: WARNING: image file not readable: media/graph0.png

Thanks! This is fixed in the updated patch. I also fixed the missing
links to sandpile tutorial (and some others as well!) and the section
tree for the programming Python tutorial, where I did some further
minor improvements.

/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:52: WAR
NING: undefined label: sage.rings.padics.tutorial (if the link has no caption the label must pre
cede a section header)                                                                          
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:60: WAR
NING: undefined label: sage.combinat.tutorial (if the link has no caption the label must precede
 a section header)                                                                              
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:88: WAR
NING: undefined label: sage.categories.primer (if the link has no caption the label must precede
 a section header)                                                                              
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/index.rst:89: WAR
NING: undefined label: sage.categories.tutorial (if the link has no caption the label must prece
de a section header)                                                                            
writing additional files... genindex search                                                     
copying images... [  2%] media/sandpile/btw.png

Yes. That's what #14091 is about (links to the reference manual). My
opinion is that we should ignore them, especially since this should be
fixed shortly by #6495.

checking consistency... /Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/functional_programming.rst:: WARNING: document isn't included in any toctree
...
/Users/slabbe/Applications/sage-5.7.beta4/devel/sage/doc/en/thematic_tutorials/tutorial-programming-python.rst:: WARNING: document isn't included in any toctree

Yes, I am not sure how to handle this. The toctree approach is not
well suited here since we want the index to include a mix of
references to local files and external files. I lamely silenced those
warnings by adding a separate "toctree.rst" document which is just
referenced from index.rst.

What do you think?

Cheers,
Nicolas

[nthiery]

comment:12

Replying to @seblabbe:

Yes, I remember vaguely but I can't remember exactly... Maybe, it was a bigger patch no? with more sections? Anyway, I looked at it and I think the sections and their order are fine.

Ok, thanks for checking!

1. However, some links do not appear as links (see attached png).

Yup. That's #14091

2. Also, links to PREP tutorials do not work.

They work in the live documentation ... The right thing to do would be
to put :ref...'s. John: do you know whether #6495 also enables links
from the thematic tutorials to the PREP's?

Cheers,
Nicolas

[nthiery]

comment:14

Actually the link to the first PREP document was wrong. I just fixed that. In waiting for a better solution, the link seem to work in the static and the live documentation ...

[nthiery]

comment:15

Reinstated the copyright notice I had inadvertently removed. Added proper patch header.

[kcrisman]

comment:16

I like this a lot after only a few minutes of looking at it! What remains to be reviewed here? (I'm not sure whether most of it has positive review or not.)

And this does not depend on #6495, correct?

[kcrisman]

comment:17

Here come some comments. First, generalities about the front page.

Or should the PREP tutorial be simply merged in the thematic tutorials (is there a compelling reason to have separate documents?)

Maybe not any more. At the time the thematic tutorials were pretty clearly thematic tutorials. Not really a lot of overlap between abelian sandpiles and an intro to doing calculus in Sage. In any case, one should keep existing links working.

Maybe that would be a next step - re-organizing all information in the Sage references. Currently there is also

• Three Lectures about Explicit Methods in Number Theory Using Sage
• Numerical Sage
• A Tour of Sage
• Constructions

Some of these things have been translated, which gives additional annoyance...

This is an index, grouped by theme, of Sage demonstrations, quick reference cards, primers, and thematic tutorials:

I only see primers and thematic tutorials. Is this old language?

Also, what is the reason for the different formatting - there is italic, regular, bold, and even tt - on the front page?

---

With respect to the iteration tutorial, on request of nthiery höchstpersönlich! Mostly very minor English stuff.

• What is the plural of "syntax"? I would use "syntaxes" as a common variant.

 You can use either of the following syntax:

• Needs comma, probably.

For example here 

• An extremely useful addition is

sage: [i^2 if i%2 == 1 else 2 for i in range(10)]
[2, 1, 2, 9, 2, 25, 2, 49, 2, 81]

The syntax has to be perfect. Does this work for ones with also for j in range(10) and so forth?

• This phrase has no end-parenthesis.

(hint:use srange() ...

• "built"

Iterators are build using parentheses:

• "Iterators can be used as arguments" or "An iterator can be used ..." - I think you mean the latter, though.

An iterators can

• With respect to this:

You can get the list of the results that are not yet consumed:

What happens if you try to continue the iterator now? I think that would be useful to warn folks.

sage: it.next()
---------------------------------------------------------------------------
StopIteration                             Traceback (most recent call last)

StopIteration: 

• "give the same result; however, the second"

give the same results; however the second 

• Show this with an example and timeit or something. Maybe untested.

Using a list would be much slower here:

• "counter example" should be one word in English.
• "and a function with tests" should be "and a function which tests
• "interesting but demonstrating" could be "interesting beyond demonstrating", though that is more of a style choice
• "Finally many" should be "Finally, many"
• Make sure these are marked # not tested!

sage: for p in Partitions(): print p
sage: for p in Primes(): print p

• Finally, I think that something about iterables should mention zip and friends. Or is that in a previous tutorial?

Overall I like it, though!

[kcrisman]

comment:18

Python tutorial:

• Dive into Python does still exist because of the license, but the author has essentially repudiated it. In any case, the link is broken.
• "The elements of a set must be hashable:" - do these readers know what that means? Give an example of something that isn't.
• "Blocks are delimited thanks to indentation." Hmm. It works, but seems stilted. Maybe "solely by means of" or "by means of" or "using" or something like that.
• Some examples of all those control structures would be good.
• "Todo Introduction to the debugger." To do?
• With range, probably you should at least make some mention of xrange, srange, sxrange, and friends and what they do. Edit: point to further down where you do.
• "The integer generated by range() are python int‘s" should have "integers" and "Python", probably.
• I'm a little confused about the structure of this document. You have this big list of stuff, and then exercises, and then magically lots of explanation of the stuff (like control structures) you glossed over earlier. ??? There is some redundancy, I think.
• Again, I highly recommend pointing out zip.
• "That is, it cannot be changed once it is created." Maybe talk about why that might be useful.

[kcrisman]

Changed reviewer from Samuel Lelièvre, Sébastien Labbé to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman

[kcrisman]

comment:19

Front page:

• I figured out the different typefaces - it's the different types of links. Italics only for Sphinx links. I don't know whether this is worth fixing - after Build the reference manual incrementally #6495 it should be easy. The :class: link probably should be different, though.
• I'm torn between putting the programming ones immediately after the intro ones or having them where they are. What do you think?
• Modeling Mathematics - that could be very confusing. I'd use a word other than "modeling", as that means something very different to most people.
• If you want to add even more things, please finish the review of the Quickstarts at Add quickstarts from PREP workshops to standard documentation #13381!

The introductory tutorial:

• "If you are browsing this document as a static web page, " - probably add something here that the active instructions assume that you are browsing it live. That's implicit, but explicit is better than implicit, according to Python…
• "mathematics like this sin(x)−y3 by using dollar signs" - maybe one should have \sin or something? The "sin" shouldn't be italicized.
• "Compute the products: M∗v and v∗M." - I'd use \cdot here
• "Still, it is possible to define symbolic functions without first defining its variables:" - "their variables", maybe
• "colour it red" - I don't know whether US English is the Sage standard. If it is, make it "color" :-)

Patchbot is giving this a green light, so I'd say fix the (mostly very minor) things I pointed out and you've got a nice upgrade to the Sage documentation on your hands!

[nthiery]

comment:20

Hi Karl!

Thanks for the proofreading and suggestions!

Replying to @kcrisman:

Python tutorial:

• Dive into Python does still exist because of the license, but the author has essentially repudiated it. In any case, the link is broken.

Link fixed. It remains good stuff!

• "The elements of a set must be hashable:" - do these readers know what that means? Give an example of something that isn't.

I added a TODO at the end about those.

• "Todo Introduction to the debugger." To do?

This is just using the standard Sphinx markup .. TODO::

• With range, probably you should at least make some mention of xrange, srange, sxrange, and friends and what they do. Edit: point to further down where you do.

Done.

• I'm a little confused about the structure of this document. You have this big list of stuff, and then exercises, and then magically lots of explanation of the stuff (like control structures) you glossed over earlier. ??? There is some redundancy, I think.

Yeah, indeed. This stems from the fact that we usually run this tutorial by having someone gloss over the first part and then have the student work on their own on the rest.

• Again, I highly recommend pointing out zip.

+1. It's mentionned later on.

• "That is, it cannot be changed once it is created." Maybe talk about why that might be useful.

Done.

Altogether, it could use some reorganisation and complements not perfect. However I would go for getting this in and improving it further in a later ticket! Ok with that?

[nthiery]

comment:21

Replying to @kcrisman:

Front page:

• I figured out the different typefaces - it's the different types of links. Italics only for Sphinx links. I don't know whether this is worth fixing - after Build the reference manual incrementally #6495 it should be easy. The :class: link probably should be different, though.

Agreed, this is ugly. But it's about style and not content. So yes,
that should be for another ticket.

• I'm torn between putting the programming ones immediately after the intro ones or having them where they are. What do you think?

I just added a link from the intro to the programming tutorials.

• Modeling Mathematics - that could be very confusing. I'd use a word other than "modeling", as that means something very different to most people.

I see the potential confusion. Yet I am strongly attached to the word
Modeling, because that's really what we are doing (in the sense of
http://en.wikipedia.org/wiki/Object-oriented_modeling, though we don't
necessarily have to use only object-oriented techniques). I changed
the title to "Modeling Mathematics on a computer". Is this better?

• If you want to add even more things, please finish the review of the Quickstarts at Add quickstarts from PREP workshops to standard documentation #13381!

:-)

This sounds nice! I'll try to have a more detailed look! For now I'll
focus on getting those in before they rot away.

The introductory tutorial:

• "If you are browsing this document as a static web page, " - probably add something here that the active instructions assume that you are browsing it live. That's implicit, but explicit is better than implicit, according to Python…

• "mathematics like this sin(x)−y3 by using dollar signs" - maybe one should have \sin or something? The "sin" shouldn't be italicized.

The \ is there in the .rst file.

• "Still, it is possible to define symbolic functions without first defining its variables:" - "their variables", maybe
• "colour it red" - I don't know whether US English is the Sage standard. If it is, make it "color" :-)

I think it is.

Patchbot is giving this a green light, so I'd say fix the (mostly very minor) things I pointed out and you've got a nice upgrade to the Sage documentation on your hands!

:-)

Thanks again for the review!

[nthiery]

comment:22

Replying to @kcrisman:

Here come some comments. First, generalities about the front page.

Or should the PREP tutorial be simply merged in the thematic tutorials (is there a compelling reason to have separate documents?)

Maybe not any more. At the time the thematic tutorials were pretty
clearly thematic tutorials. Not really a lot of overlap between
abelian sandpiles and an intro to doing calculus in Sage.

Ok.

In any case, one should keep existing links working.

Definitely!

Maybe that would be a next step - re-organizing all information in the Sage references. Currently there is also

• Three Lectures about Explicit Methods in Number Theory Using Sage
• Numerical Sage
• A Tour of Sage
• Constructions

Some of these things have been translated, which gives additional annoyance...

Yup. Do you mind opening a ticket for this?

This is an index, grouped by theme, of Sage demonstrations, quick reference cards, primers, and thematic tutorials:

I only see primers and thematic tutorials. Is this old language?

No it's new language :-) There are a bunch of demos in the
Sage-Combinat queue. I commented it out for later.

With respect to the iteration tutorial, on request of nthiery höchstpersönlich! Mostly very minor English stuff.

• What is the plural of "syntax"? I would use "syntaxes" as a common variant.

I changed this to "idioms" :-)

• An extremely useful addition is

sage: [i^2 if i%2 == 1 else 2 for i in range(10)]
[2, 1, 2, 9, 2, 25, 2, 49, 2, 81]

Added.

The syntax has to be perfect. Does this work for ones with also for j in range(10) and so forth?

I am not sure what you mean here.

What happens if you try to continue the iterator now? I think that would be useful to warn folks.

Done!

• Show this with an example and timeit or something. Maybe untested.

Using a list would be much slower here:

Done.

• Make sure these are marked # not tested!

sage: for p in Partitions(): print p
sage: for p in Primes(): print p

Better be indeed :-) Done!

• Finally, I think that something about iterables should mention zip and friends. Or is that in a previous tutorial?

It is!

Overall I like it, though!

:-)

[nthiery]

Attachment: trac_14090-thematic_tutorials-nt.patch.gz

[nthiery]

Changed reviewer from Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg

[nthiery]

comment:23

Status: ready to go, assuming the patchbot goes green.

• The two first tutorials have been reviewed in depth by Samuel Lelièvre
  during the Sage days in Bobo Dioulasso.

• Sébastien, John, Karl checked the index page

• I proofread the last tutorial

• Karl and Darij reproofread all documents. I implemented all changes by Darij.

• The link to the PREP document seem to work. Intersphinx linking
  would be nicer. But that is for later!

Thanks everybody!

[kcrisman]

comment:24

I have a couple minor quibbles yet but not worth mentioning as they are to some extent stylistic.

HOWEVER I think you should ask Harald to reorganize the standard doc page in light of this, AND I think that somewhere in there is also the source for the Sage doc which should be reorganized in light of this. After all, that is where people will be going first, and these need to make it easy for people to get to the page organized here.

[nthiery]

comment:25

Replying to @kcrisman:

I have a couple minor quibbles yet but not worth mentioning as they are to some extent stylistic.

Further work on those tutorials in a followup ticket is welcome :-)

HOWEVER I think you should ask Harald to reorganize the standard doc page in light of this, AND I think that somewhere in there is also the source for the Sage doc which should be reorganized in light of this. After all, that is where people will be going first, and these need to make it easy for people to get to the page organized here.

Yup. I just sent him an e-mail, and added him in CC.

I can't wait for the patchbot to actually run the tests ...

[jdemeyer]

Merged: sage-5.8.beta3

[nthiery]

comment:28

Yippee!

Thanks everybody for the writing and review! That will be super handy to have all those tutorials right under hand during upcoming Sage days.

Cheers,
Nicolas

[jdemeyer]

comment:29

We don't support "et al." as Author

[jdemeyer]

Changed author from Franco Saliola, Florent Hivert, Nicolas M. Thiéry, et al. to Franco Saliola, Florent Hivert, Nicolas M. Thiéry

[fchapoton]

comment:30

yet another TAB removed in the desc field.