Add thematic tutorial to the polymake interface, based on polymake tutorials

[mkoeppe]

polymake has a number of tutorials in two formats

• polymake website html: https://polymake.org/doku.php/tutorial/start - apparently released under CC BY-NC-SA
• ipynb at https://github.com/polymake/polymake/tree/Releases/demo - apparently released under GPL

In this ticket, we add a translation of the Perl-based tutorials to Python (via the polymake pexpect interface) as a thematic tutorial.
(Upstream has been contacted regarding precise license status / possible relicensing under CC-BY-SA or similar to make it suitable for the Sage documentation.)

(This will also serve as an extended testsuite for the polymake pexpect interface.)

Preview of one translated tutorial: https://www.math.ucdavis.edu/~mkoeppe/art/icerm-2018/index.html#polymake-tutorial-on-polytopes-translated-to-python

Depends on #28265

CC: @simon-king-jena @jplab @videlec @tscrim @sagetrac-tmonteil @dimpase [email protected]

Component: documentation

Author: Matthias Koeppe

Branch/Commit: u/mkoeppe/add_polymake_tutorial @ 59a2cc1

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

[mkoeppe]

Branch: u/mkoeppe/add_polymake_tutorial

[mkoeppe]

comment:3

First attempt at automatic conversion.

---

New commits:

a89a9fb	Add citations to polymake publications
dc29c9f	Add variant of src/bin/sage-ipynb2rst for converting polymake tutorials
50b2a9e	src/doc/en/thematic_tutorials: Add polymake tutorial

[mkoeppe]

Commit: 50b2a9e

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

624ac01	polymake: Also provide core functions
666db96	Added two missing optional tags
4e91dcc	Change format of a 'not tested' doc test annotation
05f3e61	update docs, as discussed on #24905
53c8ee6	Mention libterm-readkey-perl
b613e57	Mention libterm-readline-gnu-perl
e5c3249	polymake: Mention MOngoDB for polydb
b89376a	polymake: Update info on macOS
0c1b044	polymake: update MongoDB information for linux distros
4dacfe9	Merge branch 't/24905/public/upgrade_polymake_to_version_3_2r4' into t/26357/add_polymake_tutorial

[sagetrac-git]

Changed commit from 50b2a9e to 4dacfe9

[mkoeppe]

Changed dependencies from #26350 to #24905

[sagetrac-git]

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

470c358	Update automatically converted polymake tutorials from polymake 3.4
d8668a9	update list of polymake tutorials
1ab0889	Remove perl_intro.rst

[sagetrac-git]

Changed commit from 4dacfe9 to 1ab0889

[mkoeppe]

New commits:

470c358	Update automatically converted polymake tutorials from polymake 3.4
d8668a9	update list of polymake tutorials
1ab0889	Remove perl_intro.rst

[jhpalmieri]

comment:8

Wouldn't it make more sense to put polymake documentation in local/share/doc/polymake? I don't see any reference to Sage at all in the tutorials, so it really doesn't belong in Sage's thematic_tutorials directory. This is especially the case since this is an experimental package.

[dimpase]

comment:9

it doesn't build:

[dochtml] OSError: /home/dimpase/Sage/sagetrac-mirror/src/doc/en/thematic_tutorials/polymake/apps_graph.rst:206: WARNING: Inline interpreted text or phrase reference start-string without end-string.
Makefile:2032: recipe for target 'doc-html' failed

I agree with John that the proper place for this needs to be found.

[mkoeppe]

comment:10

Replying to @jhpalmieri:

Wouldn't it make more sense to put polymake documentation in local/share/doc/polymake? I don't see any reference to Sage at all in the tutorials, so it really doesn't belong in Sage's thematic_tutorials directory. This is especially the case since this is an experimental package.

This ticket is not ready for review. So far this is just an automatic conversion of the polymake tutorials (interactions in Perl). When done, the Perl interactions will be replaced by Sage doctests.

[jhpalmieri]

comment:11

Still, does it make sense to have a long multi-page document as part of the standard Sage documentation, based on an experimental package? Is there a way to include this as part of the polymake package, so it is only included when the package is installed?

[dimpase]

comment:12

perhaps one can wrap it as an experimental package.

[tscrim]

comment:13

I think it is a good idea to include this because it helps advertise things that Sage can do (with an add-on installed). Also, if it was included when the experimental package was installed, then essentially nobody would read it (at least, I don't think many non-developers even know where to find the built documentation). Now perhaps including everything is not what we should do, but instead distill it down to a more fundamental set of examples and capabilities with the full examples currently here as an extra file as part of the spkg's test suite.

Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?

[dimpase]

comment:14

polymake is far from being available on all platforms we support, see last comments on #24905

[simon-king-jena]

comment:15

Replying to @tscrim:

I think it is a good idea to include this because it helps advertise things that Sage can do (with an add-on installed).

The impression came across that the suggestion is to merely have the upstream (perl based!) documentation available. This would clearly not qualify as a Sage tutorial.

But even if the intention was to create a tutorial that is a SageMath tutorial (i.e., a document that exposes how to compute with polytopes in Sage using Polymake as a backend and leaving perl out of the picture): We are talking about an optional or experimental package, and so far the documentation of such packages is, by default, in SAGE_LOCAL/share/doc/.

Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?

If I understand correctly, a substantial part of the recent polymake tickets and also some threads on Sage-devel and sage-support included discussion on how to make it build. That would be reason enough
demote an optional package to an experimental one.

[mkoeppe]

comment:16

Replying to @tscrim:

Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?

1. As Dima said, at the moment there are still some (minor) portability problems:
   a) On Centos because of the layout of the Perl installation. Upstream (Benjamin Lorenz) is aware of it and is working on a fix.

b) Also (per Dima) apparently gcc 6.3 as on Debian stable is too old to build polymake.

2. Because of Perl package dependencies, the installation not yet as fully automatic as other sage packages. See Perl packages for polymake #27763 - any help and ideas there are welcome.

Polymake historically had a reputation of being hard to install, but the polymake team has made great improvements there. The remaining portability issues can be addressed in the same way as it is done for other packages.

[sagetrac-git]

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

ecb38fb	Merge tag '8.8.beta5' into t/26357/add_polymake_tutorial
e003668	Add sage doctests to apps_polytope tutorial
07636a9	Update polymake demo conversion template

[sagetrac-git]

Changed commit from 1ab0889 to 07636a9

[sagetrac-git]

Changed commit from 07636a9 to c5f533a

[sagetrac-git]

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

ccc5c0c	Add sage doctests to apps_graph tutorial
f5e66b0	Add sage doctests to apps_matroid tutorial
c5f533a	Add sage doctests to apps_fan tutorial

[sagetrac-git]

Changed commit from c5f533a to 93c99f6

[sagetrac-git]

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

93c99f6

Add sage doctests to apps_tropical tutorial

[mkoeppe]

Changed dependencies from #24905 to #28265

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

8b539c7	Remove perl_intro.rst
e6e6342	Add sage doctests to apps_polytope tutorial
2ff61b8	Update polymake demo conversion template
7d95754	Add sage doctests to apps_graph tutorial
95c47fc	Add sage doctests to apps_matroid tutorial
76a6dba	Add sage doctests to apps_fan tutorial
8420d70	Add sage doctests to apps_tropical tutorial
acc1ecb	Update section titles
d7705de	sage.env: Add POLYMAKE_DATA_DIR
5887a3b	Translate 'polymake and Optimization' tutorial to Python

[sagetrac-git]

Changed commit from 93c99f6 to 5887a3b

[mkoeppe]

comment:22

Rebased on top of #28265, 8.9.beta3

[sagetrac-git]

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

1270269

Update polymake intro and some section titles

[sagetrac-git]

Changed commit from 5887a3b to 1270269

[mkoeppe]

comment:24

The tutorials are currently listed in alphabetical order by file name; they should probably be structured in the same way as here: https://polymake.org/doku.php/user_guide/start

[sagetrac-git]

Changed commit from 1270269 to 59a2cc1

[sagetrac-git]

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

ec05386	polymake/apps_tropical.rst: Work around polymake interface limitations using getattr, get_member_function, function_call
59a2cc1	polymake/optimization.rst: Use getattr