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

[mkoeppe]

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

[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

[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

[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]

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]

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]

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]

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]

perhaps one can wrap it as an experimental package.

[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). 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]

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

[SimonKing]

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/<package name>.

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]

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

[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

[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

[git]

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

​93c99f6

Add sage doctests to apps_tropical tutorial

[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

[mkoeppe]

Rebased on top of #28265, 8.9.beta3

[git]

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

​1270269

Update polymake intro and some section titles

[mkoeppe]

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

[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