Opened 8 years ago

Closed 8 years ago

Last modified 6 years ago

#14090 closed enhancement (fixed)

Thematic tutorials: using the notebook, programming python, comprehensions

Reported by: nthiery Owned by: mvngu
Priority: major Milestone: sage-5.8
Component: documentation Keywords: thematic tutorials
Cc: sage-combinat, slabbe, novoselt, schilly Merged in: sage-5.8.beta3
Authors: Franco Saliola, Florent Hivert, Nicolas M. Thiéry Reviewers: Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by chapoton)

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.

Attachments (2)

Image 27.png (133.0 KB) - added by slabbe 8 years ago.
trac_14090-thematic_tutorials-nt.patch (82.3 KB) - added by nthiery 8 years ago.

Download all attachments as: .zip

Change History (32)

comment:1 follow-up: Changed 8 years ago by nthiery

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

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

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

comment:3 follow-up: Changed 8 years ago by jhpalmieri

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

comment:4 Changed 8 years ago by nthiery

  • Description modified (diff)
  • Status changed from new to needs_review

comment:5 in reply to: ↑ 3 Changed 8 years ago by nthiery

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

comment:6 in reply to: ↑ 2 Changed 8 years ago by nthiery

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

comment:7 Changed 8 years ago by novoselt

  • Cc novoselt added

comment:8 Changed 8 years ago by slabbe

  • Cc slabbe added; slabqc@… removed

Changed 8 years ago by slabbe

comment:9 in reply to: ↑ 1 ; follow-up: Changed 8 years ago by slabbe

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).
  1. Also, links to PREP tutorials do not work.

comment:10 follow-up: Changed 8 years ago by slabbe

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

comment:11 in reply to: ↑ 10 Changed 8 years ago by nthiery

Hi Sébastien!

Replying to slabbe:

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

comment:12 in reply to: ↑ 9 Changed 8 years ago by nthiery

Replying to slabbe:

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

  1. 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

comment:13 Changed 8 years ago by nthiery

  • Description modified (diff)

comment:14 Changed 8 years ago by nthiery

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

comment:15 Changed 8 years ago by nthiery

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

Last edited 8 years ago by nthiery (previous) (diff)

comment:16 Changed 8 years ago by kcrisman

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?

comment:17 follow-up: Changed 8 years ago by 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. 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!

comment:18 follow-up: Changed 8 years ago by 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.
  • "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.

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

  • Reviewers changed from Samuel Lelièvre, Sébastien Labbé to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman
  • Status changed from needs_review to needs_work

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 #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 #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!

comment:20 in reply to: ↑ 18 Changed 8 years ago by nthiery

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?

comment:21 in reply to: ↑ 19 Changed 8 years ago by nthiery

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 #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 #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!

comment:22 in reply to: ↑ 17 Changed 8 years ago by nthiery

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!

:-)

Changed 8 years ago by nthiery

comment:23 Changed 8 years ago by nthiery

  • Description modified (diff)
  • Reviewers changed from Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman to Samuel Lelièvre, Sébastien Labbé, Karl-Dieter Crisman, Darij Grinberg
  • Status changed from needs_work to positive_review

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!

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

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.

comment:25 in reply to: ↑ 24 Changed 8 years ago by nthiery

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

comment:26 Changed 8 years ago by schilly

  • Cc schilly added

comment:27 Changed 8 years ago by jdemeyer

  • Merged in set to sage-5.8.beta3
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:28 Changed 8 years ago by nthiery

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

comment:29 Changed 8 years ago by jdemeyer

  • Authors changed from Franco Saliola, Florent Hivert, Nicolas M. Thiéry, et al. to Franco Saliola, Florent Hivert, Nicolas M. Thiéry

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

comment:30 Changed 6 years ago by chapoton

  • Description modified (diff)

yet another TAB removed in the desc field.

Note: See TracTickets for help on using tickets.