Add tutorial for creating publication-ready images with draw_tree (#765)

* update pyproject.toml with optional dependencies for test suite and docs

* update GitHub actions to install optional dependencies when installing pygambit instead of using requirements.txt

* add doc dependencies: Cython, numpy, scipy

* try GH actions without testing docs

* Revert "try GH actions without testing docs"

This reverts commit 4d54262.

* remove pip install that is already covered by build-system in pyproject.toml

* fix typo mistake in doc dependencies list

* remove Cython, numpy and scipy from doc dependency list as these are already included in build-system or dependencies

* restore installation of build on linux job

* remove requirements.txt files

* update docs for new installation method

* update documentation instructions

* update readthedocs config

* try fixing linux build

* try again to fix linux job: let bash expand the filename first, then append extras

* Create catalog dir and move one EFG and one NFG into it from contrib/games

* ignore catalog files copied into pygambit

* add failing tests

* improve tests

* add pandas to pyproject.toml

* add test_catalog_load_invalid_slug

* create load function

* add catalog to __init__

* add games() function

* refactor to define READERS once

* Big refactor to get catalog files from catalog dir external to pygambit

* update Makefile.am for the 2 examples we moved into the catalog so far

* update Game.comment to be Game.description in Python code

* Revert "update Game.comment to be Game.description in Python code"

This reverts commit 7490ae6.

* Add initial update catalog script and RST page

* rename table headers on output df from game() func

* add generating the catalog csv for docs into GH actions

* Revert "add generating the catalog csv for docs into GH actions"

This reverts commit bd3c1f3.

* refactor update script so its run from repo root

* update readthedocs to build the catalog csv before docs build

* add function which updates Makefile.am

* use a proper path for CATALOG_CSV

* tidy update script

* use explicit python executable from the virtualenv to create CSV for catalog docs table in readthedocs yml

* add developer doc for updating the catalog

* Don't update Makefile.am by default

* consistency in notebook comment

* demo loading from catalog in tutorial 1

* load from catalog for game examples in advanced tutorials

* Try using pip instead of setuptools to ensure pyproject.toml deps installed for readthedocs build

* remove deleted contrib games from Makefile.am

* add a warning about moving games from contrib

* check if pandas duplications error exists if we dont save outputs on notebooks

* fix problem with print function

* resave notebook outputs

* Update writer.cc

* move catalog update script into build support

* rename script

* rename var

* update path to catalog update script in readthedocs yml and docs page

* move myserson fig into subfolder

* clarify script usage

* add test_catalog_load_subdir_slug

* update makefile

* update agent nb

* add test for slug in subdir of catalog

* update games func to list slugs correctly

* update test to avoid duplicates

* fix code for handling slugs that duplicates of those in subfolders

* tidy the games() refactor

* resave notebook

* strip nb outputs

* remove modification to games() that was fixing a local issue

* fix the update script to get correct paths

* remove unused var

* Add Windows handling

* fix incorrect var name and make consistent

* use as_posix for slugs

* add new notebook

* upgrade draw_tree version to 0.4.0

* 2smp game looks good

* add sections on saving images and further adjustments

* update headers

* update header further

* add comment

* clear saved outputs from all tutorials

* typo

* tidy read and save sections

* renumber and reorder tutorials

* update image to use sublevel_scaling

* clear outputs

* revert makefile changes

* move games back to contrib

* Move 2smp back again since it's used by tutorial 4

* tidy saving sections of tutorials 1 and 2

---------

Co-authored-by: Ted Turocy <ted.turocy@gmail.com>

Author: edwardchalstrey1

Makefile.am

@@ -101,7 +101,6 @@ EXTRA_DIST = \
 	src/gui/bitmaps/zoom1.xpm \
 	src/gui/bitmaps/gambitrc.rc \
 	contrib/games/2s2x2x2.efg \
-	contrib/games/2smp.efg \
 	contrib/games/2x2x2.efg \
 	contrib/games/4cards.efg \
 	contrib/games/artist1.efg \
@@ -236,6 +235,7 @@ EXTRA_DIST = \
 	contrib/games/yamamoto.nfg \
 	contrib/games/zero.nfg \
 	src/README.rst \
+	catalog/2smp.efg \
 	catalog/myerson1991/fig4_2.efg \
 	catalog/selten1975/fig1.efg \
 	catalog/selten1975/fig2.efg \

contrib/games/2smp.efg catalog/2smp.efgcontrib/games/2smp.efg renamed to catalog/2smp.efg

@@ -8,8 +8,9 @@ See installation instructions in the :ref:`install` section.
 
 
 For newcomers to Gambit, we recommend reading through the PyGambit tutorials, which demonstrate the API's key capabilities for analyzing and solving games.
-These tutorials are available to be run interactively as Jupyter notebooks, see :ref:`local_tutorials`.
-All of the tutorials assume a basic knowledge of programming in Python.
+All of these tutorials assume a basic knowledge of programming in Python.
+
+You can run the tutorials interactively as Jupyter notebooks, see :ref:`local_tutorials`.
 
 New user tutorials
 ------------------
@@ -20,10 +21,10 @@ They are numbered in the order they should be read.
 .. toctree::
    :maxdepth: 2
 
-   tutorials/running_locally
    tutorials/01_quickstart
    tutorials/02_extensive_form
    tutorials/03_stripped_down_poker
+   tutorials/04_creating_images
 
 Advanced user tutorials
 -----------------------

doc/pygambit.rst

@@ -311,7 +311,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "24f36b0d",
+   "id": "3dfbf327",
    "metadata": {},
    "source": [
     "Saving and reading strategic form games to and from file\n",
@@ -320,35 +320,18 @@
     "You can use Gambit to save games to, and read from files.\n",
     "The specific format depends on whether the game is normal or extensive-form.\n",
     "\n",
-    "Here we'll save the Prisoner's Dilemma (Normal-form) to the `.nfg` format."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "f58eaa77",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# g.to_nfg(\"prisoners_dilemma.nfg\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "e373be1e",
-   "metadata": {},
-   "source": [
-    "You can easily restore the game object from file like so:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4119a2ac",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# gbt.read_nfg(\"prisoners_dilemma.nfg\")"
+    "Here we'll save the Prisoner's Dilemma (Normal-form) to the `.nfg` format.\n",
+    "Run these lines of code in new code cells if you're running the tutorial locally:\n",
+    "\n",
+    "```python\n",
+    "g.to_nfg(\"prisoners_dilemma.nfg\")\n",
+    "```\n",
+    "\n",
+    "You can easily restore the game object from file like so:\n",
+    "\n",
+    "```python\n",
+    "gbt.read_nfg(\"prisoners_dilemma.nfg\")\n",
+    "```"
    ]
   }
  ],

doc/tutorials/01_quickstart.ipynb

@@ -314,67 +314,17 @@
     "The specific format depends on whether the game is normal or extensive-form.\n",
     "\n",
     "Here we'll save the Trust game (extensive-form) to the `.efg` format.\n",
-    "Uncomment these lines of code if you're running the tutorial locally:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "37c51152",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# g.to_efg(\"trust_game.efg\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "0eb31525",
-   "metadata": {},
-   "source": [
-    "You can easily restore the game object from file like so:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "0d86a750",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# gbt.read_efg(\"trust_game.efg\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "182f2424-274e-4044-84ff-3323cd70ec68",
-   "metadata": {},
-   "source": [
-    "You can also use the `draw_tree` package to save the game in the `.ef` format which encodes layout information.\n",
-    "This can in turn be used to render the image for use in publications, for example as a `.png` (there are also `.pdf` and `.tex` options, see [draw_tree](https://github.com/gambitproject/draw_tree)):"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "1bab777f-8a0b-4f1e-9c0c-270690288243",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# from draw_tree import generate_png\n",
-    "# draw_tree(g, save_to=\"trust_game.ef\")\n",
-    "# trust_game_png = generate_png(\"trust_game.ef\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "2b715221-e427-4092-ad2f-9f4f2b548fa4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# from IPython.display import Image\n",
-    "# Image(trust_game_png)"
+    "Run these lines of code in new code cells if you're running the tutorial locally:\n",
+    "\n",
+    "```python\n",
+    "g.to_efg(\"trust_game.efg\")\n",
+    "```\n",
+    "\n",
+    "You can easily restore the game object from file like so:\n",
+    "\n",
+    "```python\n",
+    "gbt.read_efg(\"trust_game.efg\")\n",
+    "```"
    ]
   },
   {