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 lorenz@math.tu-berlin.de

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?