#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: |
Description (last modified by )
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)
Change History (32)
comment:1 follow-up: ↓ 9 Changed 8 years ago by
comment:2 follow-up: ↓ 6 Changed 8 years ago by
I think that intersphinx linking to the reference manual should be fixed by #6495. See also a sage-support thread.
comment:3 follow-up: ↓ 5 Changed 8 years ago by
By the way, was the sandpile
document removed from the top-level index file intentionally?
comment:4 Changed 8 years ago by
- Description modified (diff)
- Status changed from new to needs_review
comment:5 in reply to: ↑ 3 Changed 8 years ago by
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
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
- Cc novoselt added
comment:8 Changed 8 years ago by
- Cc slabbe added; slabqc@… removed
Changed 8 years ago by
comment:9 in reply to: ↑ 1 ; follow-up: ↓ 12 Changed 8 years ago by
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.
- However, some links do not appear as links (see attached png).
- Also, links to PREP tutorials do not work.
comment:10 follow-up: ↓ 11 Changed 8 years ago by
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
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
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!
- However, some links do not appear as links (see attached png).
Yup. That's #14091
- 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
- Description modified (diff)
comment:14 Changed 8 years ago by
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
Reinstated the copyright notice I had inadvertently removed. Added proper patch header.
comment:16 Changed 8 years ago by
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: ↓ 22 Changed 8 years ago by
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 alsofor 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: ↓ 20 Changed 8 years ago by
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 ofxrange
,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: ↓ 21 Changed 8 years ago by
- 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
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 ofxrange
,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
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
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
comment:23 Changed 8 years ago by
- 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: ↓ 25 Changed 8 years ago by
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
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
- Cc schilly added
comment:27 Changed 8 years ago by
- 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
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:30 Changed 6 years ago by
- Description modified (diff)
yet another TAB removed in the desc field.
Sébastien: can you have a look at the main index page? We had discussed it together last time I was in Montreal.