Add initial version of games catalog

.gitignore

@@ -50,3 +50,5 @@ Gambit.app/*
 *.ef
 build_support/msw/gambit.wxs
 build_support/osx/Info.plist
+src/pygambit/catalog
+doc/catalog.csv

.readthedocs.yml

@@ -13,9 +13,13 @@ build:
     - libgmp-dev
     - pandoc
     - texlive-full
+  jobs:
+    # Create CSV for catalog table in docs
+    post_install:
+      - $READTHEDOCS_VIRTUALENV_PATH/bin/python src/pygambit/update_catalog.py
 
 python:
   install:
     - requirements: doc/requirements.txt
-    - method: setuptools
+    - method: pip
       path: "."

MANIFEST.in

@@ -1,6 +1,7 @@
 recursive-include src/core *.cc *.h *.imp
 recursive-include src/games *.cc *.h *.imp
 recursive-include src/solvers *.c *.cc *.h *.imp
+recursive-include catalog *
 include src/gambit.h
 include src/pygambit/*.pxd
 include src/pygambit/*.pyx

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 \
@@ -169,7 +168,6 @@ EXTRA_DIST = \
 	contrib/games/my_3-3d.efg \
 	contrib/games/my_3-3e.efg \
 	contrib/games/my_3-4.efg \
-	contrib/games/myerson.efg \
 	contrib/games/nim7.efg \
 	contrib/games/nim.efg \
 	contrib/games/palf2.efg \
@@ -195,7 +193,6 @@ EXTRA_DIST = \
 	contrib/games/2x2a.nfg \
 	contrib/games/2x2const.nfg \
 	contrib/games/2x2.nfg \
-	contrib/games/2x2x2.nfg \
 	contrib/games/2x2x2x2.nfg \
 	contrib/games/2x2x2x2x2.nfg \
 	contrib/games/3x3x3.nfg \
@@ -224,7 +221,6 @@ EXTRA_DIST = \
 	contrib/games/mixdom2.nfg \
 	contrib/games/mixdom.nfg \
 	contrib/games/oneill.nfg \
-	contrib/games/pd.nfg \
 	contrib/games/perfect1.nfg \
 	contrib/games/perfect2.nfg \
 	contrib/games/perfect3.nfg \
@@ -240,7 +236,11 @@ EXTRA_DIST = \
 	contrib/games/winkels.nfg \
 	contrib/games/yamamoto.nfg \
 	contrib/games/zero.nfg \
-	src/README.rst
+	src/README.rst \
+	catalog/2smp.efg \
+	catalog/2x2x2.nfg \
+	catalog/myerson_fig_4_2.efg \
+	catalog/pd.nfg
 
 core_SOURCES = \
     src/core/core.h \

catalog/__init__.py

@@ -0,0 +1,51 @@
+from importlib.resources import as_file, files
+
+import pandas as pd
+
+import pygambit as gbt
+
+# Use the full string path to the virtual package we created
+_CATALOG_RESOURCE = files(__name__)
+
+READERS = {
+    ".nfg": gbt.read_nfg,
+    ".efg": gbt.read_efg,
+}
+
+
+def load(slug: str) -> gbt.Game:
+    """
+    Load a game from the package catalog.
+    """
+    for suffix, reader in READERS.items():
+        resource_path = _CATALOG_RESOURCE / f"{slug}{suffix}"
+
+        if resource_path.is_file():
+            # as_file ensures we have a real filesystem path for the reader
+            with as_file(resource_path) as path:
+                return reader(str(path))
+
+    raise FileNotFoundError(f"No catalog entry called {slug}.nfg or {slug}.efg")
+
+
+def games() -> pd.DataFrame:
+    """
+    List games available in the package catalog.
+    """
+    records: list[dict[str, str]] = []
+
+    # iterdir() works directly on the Traversable object
+    for resource_path in sorted(_CATALOG_RESOURCE.iterdir()):
+        reader = READERS.get(resource_path.suffix)
+
+        if reader is not None and resource_path.is_file():
+            with as_file(resource_path) as path:
+                game = reader(str(path))
+                records.append(
+                    {
+                        "Game": resource_path.stem,
+                        "Title": game.title,
+                    }
+                )
+
+    return pd.DataFrame.from_records(records, columns=["Game", "Title"])

doc/catalog.rst

@@ -0,0 +1,8 @@
+Catalog of games
+================
+
+.. csv-table::
+   :file: catalog.csv
+   :header-rows: 1
+   :widths: 20, 80
+   :class: tight-table

doc/developer.catalog.rst

@@ -0,0 +1,45 @@
+Updating the Games Catalog
+==========================
+
+This page covers the process for contributing to and updating Gambit's :ref:`Games Catalog <pygambit-catalog>`.
+To do so, you will need to have the `gambit` GitHub repo cloned and be able to submit pull request via GitHub;
+you may wish to first review the :ref:`contributor guidelines <contributing>`.
+
+You can add games to the catalog saved in a valid representation :ref:`format <file-formats>`.
+Currently supported representations are:
+
+- `.efg` for extensive form games
+- `.nfg` for normal form games
+
+Add new games
+-------------
+
+1. **Create the game file:**
+
+   Use either :ref:`pygambit <pygambit>`, the Gambit :ref:`CLI <command-line>` or :ref:`GUI <section-gui>` to create and save game in a valid representation :ref:`format <file-formats>`.
+
+2. **Add the game file:**
+
+   Create a new branch in the ``gambit`` repo. Add your new game file(s) inside the ``catalog`` dir and commit them.
+
+3. **Update the catalog:**
+
+   Use the ``update_catalog.py`` script to update Gambit's documentation & build files.
+
+   .. code-block:: bash
+
+       python src/pygambit/update_catalog.py --build
+
+   .. note::
+
+      Run this script in a Python environment where ``pygambit`` itself is also :ref:`installed <build-python>`.
+
+   .. warning::
+
+      This script updates `Makefile.am` with the game file added to the catalog, but if you moved games that were previously in `contrib/games` you'll want to manually remove those files from `EXTRA_DIST`.
+
+4. **Submit a pull request to GitHub with all changes.**
+
+   .. warning::
+
+      Make sure you commit all changed files e.g. run ``git add --all`` before committing and pushing.

doc/developer.contributing.rst

@@ -1,3 +1,5 @@
+.. _contributing:
+
 Contributing to Gambit
 ======================
 

doc/developer.rst

@@ -11,3 +11,4 @@ This section contains information for developers who want to contribute to the G
 
    developer.build
    developer.contributing
+   developer.catalog

doc/index.rst

@@ -64,6 +64,7 @@ We recommended most new users install the PyGambit Python package and read the a
    pygambit
    tools
    gui
+   catalog
    samples
    developer
    formats