move the document "Python Functional Programming for Mathematicians" to the classification "Thematic Tutorials"

[sagetrac-mvngu]

The new documentation classification "Thematic Tutorials" aims to include various in-depth documentation/tutorials on specific topics. Here, we move the chapter Python Functional Programming for Mathematicians to the "Thematic Tutorials" classification. The original proposal can be found on sage-devel and sage-combinat-devel.

Notes: The current ticket needs to be coordinated with #8470.

Prerequisites: #8480, #8464

CC: @nexttime @qed777

Component: documentation

Keywords: Sage HOWTOs

Author: Minh Van Nguyen, John Palmieri

Reviewer: John Palmieri, Leif Leonhardy

Merged: sage-4.5.2.rc0

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

[sagetrac-mvngu]

Author: Minh Van Nguyen

[sagetrac-mvngu]

Attachment: trac_8465-functional.patch.gz

based on Sage 4.3.4.alpha1

[haraldschilly]

comment:5

i hope that's the correct place to point out some ideas i have:
(at least, i found them
very useful to know when i coded something recently)

1. reduce will be part of the functools module in python 3. might be
   helpful to import it from there to make it forward compatible
   http://docs.python.org/library/functools.html <- or at least you might
   wanna add a link to that module in the bottom section.

2. http://docs.python.org/library/itertools.html#itertools.starmap is
   quite cool if you have "izip"ed values for the function arguments.
   i.e.
   starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000. it's like f(a,b) vs. f(*c)

3. Besides that, have you explained the generator concept with the
   "yield" keyword? I'm not sure if that counts as functional programming
   but it is a nice topic in that context.

[sagetrac-mjordan7]

comment:6

Tested well, and looks good on Boxen. In the styles of programming section, the object-oriented example seemed a little contrived, and I would say was bad style to make an object for adding two things. I believe a better example would to use comparison instead of adding. Something procedural

def compare(a, b)
return a - b;

versus like this for object-oriented

def class Comparable
def compare(b)
return self - b;

~Mark

[malb]

comment:7

Minh, I'm setting this to needs work in light of the comments by Mark. If you don't feel this is justified could you briefly explain why here and then change it back to needs review?

[jhpalmieri]

comment:8

Two other comments: I don't think we need the file doc/en/thematic_tutorials/Makefile. Also, the file index.rst should include a line for the group_theory document.

[jhpalmieri]

comment:10

Here is a new patch. This removes the file Makefile and adds group_theory and a descriptive sentence to index.rst.

As far as the comments above, they are beyond the scope of this ticket. The point of this ticket was to move the file functional_programming.rst from the constructions document to the thematic tutorials document. I think that some of the comments have some merit, but they involve revising that document. I've opened #9612 for those revisions.

So I'm returning this to "needs review". I'm actually happy with the original ticket, so the only things that need reviewing are the changes I made to index.rst, as well as the removal of Makefile.

[nexttime]

Reviewer: John Palmieri, Leif Leonhardy

[nexttime]

comment:11

sphinx-build -b html -d /home/leif/sage-4.5.2.alpha1/devel/sage/doc/output/doctrees/en/constructions    /home/leif/sage-4.5.2.alpha1/devel/sage/doc/en/constructions /home/leif/sage-4.5.2.alpha1/devel/sage/doc/output/html/en/constructions
Running Sphinx v0.6.3
...
/home/leif/sage-4.5.2.alpha1/devel/sage/doc/en/constructions/index.rst:28: (WARNING/2) toctree references unknown document u'functional_programming'
...
build succeeded, 1 warning.

...

sphinx-build -b html -d /home/leif/sage-4.5.2.alpha1/devel/sage/doc/output/doctrees/en/thematic_tutorials    /home/leif/sage-4.5.2.alpha1/devel/sage/doc/en/thematic_tutorials /home/leif/sage-4.5.2.alpha1/devel/sage/doc/output/html/en/thematic_tutorials
Running Sphinx v0.6.3
loading pickled environment... not found
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [ 33%] functional_programming
reading sources... [ 66%] group_theory
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 33%] functional_programming
writing output... [ 66%] group_theory
writing output... [100%] index

writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished.  The built documents can be found in /home/leif/sage-4.5.2.alpha1/devel/sage/doc/output/html/en/thematic_tutorials

...

(The bottom part is just informational.)

So just little work needed (dangling reference).

Thanks though for fixing this "eternal" error... ;-)

Changing this to "critical" and "defect", since actually this patch fixes a Sphinx build error.

[nexttime]

Work Issues: Update dangling reference

[nexttime]

Changed author from Minh Van Nguyen to Minh Van Nguyen, John Palmieri

[jhpalmieri]

Attachment: trac_8465-v2.patch.gz

based on 4.5.2.alpha1. apply only this patch.

[jhpalmieri]

comment:12

This patch should fix that problem. (Only change: remove one line in doc/en/constructions/index.rst.)

[jhpalmieri]

Changed work issues from Update dangling reference to none

[nexttime]

comment:14

Hmmm, I might be stupid, but I cannot find the Thematic Tutorials in (or from) the main index devel/sage/doc/output/html/en/index.html.

Sorry, didn't look for that before...

The (re)build of the HTML documents now works as expected (without new warnings).

[jhpalmieri]

comment:15

Hmmm, I might be stupid, but I cannot find the Thematic Tutorials in (or from) the main index devel/sage/doc/output/html/en/index.html.

I think it gets added in #8442.

[nexttime]

comment:16

Replying to @jhpalmieri:

Hmmm, I might be stupid, but I cannot find the Thematic Tutorials in (or from) the main index devel/sage/doc/output/html/en/index.html.

I think it gets added in #8442.

So can you merge the patch to doc/en/website/templates/index.html from https://github.com/sagemath/sage-prod/files/10648393/trac_8442-config.patch.gz (if that's the correct one)?

[jhpalmieri]

apply on top of trac_8465-v2.patch

[jhpalmieri]

comment:17

Attachment: trac_8442-config.patch.gz

Okay, here you go.

[jhpalmieri]

comment:18

I should have renamed the new patch. Despite its name, it does belong on this ticket, #8465. The commit message has the correct ticket number.

If this is merged, we'll need to rebase some of the patches related to #8470, since some of those include the same changes to conf.py and to website/templates/index.html.

[nexttime]

comment:19

Cool!

Note to the release managers

Apply only trac_8465-v2.patch and (despite its name) trac_8442-config.patch.

(The latter is only a part of https://github.com/sagemath/sage-prod/files/10648393/trac_8442-config.patch.gz)

[qed777]

Fix website index.html typo. Apply on top of other two patches.

[qed777]

Merged: sage-4.5.2.rc0

[qed777]

comment:22

Attachment: trac_8465-fix_typo.patch.gz

Replying to @nexttime:

Note to the release managers

Apply only trac_8465-v2.patch and (despite its name) trac_8442-config.patch.

I'm merging these and a new attachment: trac_8465-fix_typo.patch into 4.5.2.rc0. Can someone please check the latter? There's no need to add me as an author.

[jhpalmieri]

comment:23

The typo patch is fine.