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 build_support/catalog/update.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 \

build_support/catalog/update.py

@@ -0,0 +1,74 @@
+import argparse
+from pathlib import Path
+
+import pygambit as gbt
+
+CATALOG_CSV = Path(__file__).parent.parent.parent / "doc" / "catalog.csv"
+CATALOG_DIR = Path(__file__).parent.parent.parent / "catalog"
+MAKEFILE_AM = Path(__file__).parent.parent.parent / "Makefile.am"
+
+
+def update_makefile():
+    """Update the Makefile.am with all games from the catalog."""
+
+    # Using rglob("*") to find files in all subdirectories
+    slugs = []
+    for resource_path in sorted(CATALOG_DIR.rglob("*.efg")):
+        if resource_path.is_file():
+            rel_path = resource_path.relative_to(CATALOG_DIR)
+            slugs.append(str(rel_path))
+    for resource_path in sorted(CATALOG_DIR.rglob("*.nfg")):
+        if resource_path.is_file():
+            rel_path = resource_path.relative_to(CATALOG_DIR)
+            slugs.append(str(rel_path))
+
+    game_files = []
+    for slug in slugs:
+        game_files.append(f"catalog/{slug}")
+    game_files.sort()
+
+    with open(MAKEFILE_AM, encoding="utf-8") as f:
+        content = f.readlines()
+
+    with open(MAKEFILE_AM, "w", encoding="utf-8") as f:
+        in_gamefiles_section = False
+        for line in content:
+            # Add to the EXTRA_DIST after the README.rst line
+            if line.startswith("	src/README.rst \\"):
+                in_gamefiles_section = True
+                f.write("	src/README.rst \\\n")
+                for gf in game_files:
+                    if gf == game_files[-1]:
+                        f.write(f"\t{gf}\n")
+                    else:
+                        f.write(f"\t{gf} \\\n")
+                f.write("\n")
+            elif in_gamefiles_section:
+                if line.strip() == "":
+                    in_gamefiles_section = False
+                continue  # Skip old gamefiles lines
+            else:
+                f.write(line)
+
+    with open(MAKEFILE_AM, encoding="utf-8") as f:
+        updated_content = f.readlines()
+
+    if content != updated_content:
+        print(f"Updated {str(MAKEFILE_AM)}")
+    else:
+        print(f"No changes to add to {str(MAKEFILE_AM)}")
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--build", action="store_true")
+    args = parser.parse_args()
+
+    # Create CSV used by RST docs page
+    gbt.catalog.games().to_csv(CATALOG_CSV, index=False)
+    print(f"Generated {CATALOG_CSV} for use in local docs build. DO NOT COMMIT.")
+
+    # Update the Makefile.am with the current list of catalog files
+    if args.build:
+        update_makefile()

catalog/__init__.py

@@ -0,0 +1,60 @@
+from importlib.resources import as_file, files
+from pathlib import Path
+
+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.
+    """
+    slug = str(Path(slug)).replace("\\", "/")
+
+    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, including subdirectories.
+    """
+    records: list[dict[str, str]] = []
+
+    # Using rglob("*") to find files in all subdirectories
+    for resource_path in sorted(_CATALOG_RESOURCE.rglob("*")):
+        reader = READERS.get(resource_path.suffix)
+
+        if reader is not None and resource_path.is_file():
+
+            # Calculate the path relative to the root resource
+            # and remove the suffix to get the "slug"
+            rel_path = resource_path.relative_to(_CATALOG_RESOURCE)
+            slug = rel_path.with_suffix("").as_posix()
+
+            with as_file(resource_path) as path:
+                game = reader(str(path))
+                records.append(
+                    {
+                        "Game": slug,
+                        "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.py`` script to update Gambit's documentation & build files.
+
+   .. code-block:: bash
+
+       python build_support/catalog/update.py --build
+
+   .. note::
+
+      Run this script in a Python environment where ``pygambit`` itself is also :ref:`installed <build-python>`.
+
+   .. warning::
+
+      Running the script with the ``--build`` flag updates `Makefile.am`. If you moved games that were previously in `contrib/games` you'll need to also 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