[WIP] Tutorial/732

.github/workflows/python.yml

@@ -21,16 +21,15 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools build cython wheel
-          pip install -r tests/requirements.txt
-          pip install -r doc/requirements.txt
+          python -m pip install build
       - name: Build source distribution
         run:
           python -m build
       - name: Build from source distribution
         run: |
           cd dist
-          pip install -v pygambit*.tar.gz
+          sdist=$(ls pygambit-*.tar.gz)
+          pip install -v "${sdist}[test,doc]"
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -50,12 +49,9 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools build cython wheel
-          pip install -r tests/requirements.txt
-          pip install -r doc/requirements.txt
       - name: Build extension
         run: |
-          python -m pip install -v .
+          python -m pip install -v .[test,doc]
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -75,12 +71,9 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools build cython wheel
-          pip install -r tests/requirements.txt
-          pip install -r doc/requirements.txt
       - name: Build extension
         run: |
-          python -m pip install -v .
+          python -m pip install -v .[test,doc]
       - name: Run tests
         run: pytest --run-tutorials
 
@@ -100,11 +93,8 @@ jobs:
       - name: Set up dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools build cython wheel
-          pip install -r tests/requirements.txt
-          pip install -r doc/requirements.txt
       - name: Build extension
         run: |
-          python -m pip install -v .
+          python -m pip install -v .[test,doc]
       - name: Run tests
         run: pytest --run-tutorials

.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,14 @@ 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: "."
+      extra_requirements:
+        - doc

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.build.rst

@@ -188,7 +188,11 @@ Use `pip` to install from the **root directory of the source tree**:
 
    python -m venv venv
    source venv/bin/activate
-   python -m pip install .
+   python -m pip install .[test,doc]
+
+.. tip::
+
+   The "test" and "doc" optional dependencies are useful for developers wishing to run the test suite or build this documentation locally.
 
 
 Once installed, simply ``import pygambit`` in your Python shell or

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
 ======================
 
@@ -102,19 +104,16 @@ Be sure to familiarise yourself with :ref:`contributing-code` before reading thi
 By default, pull requests on GitHub will trigger the running of Gambit's test suite using GitHub Actions.
 You can also run the tests locally before submitting your pull request, using `pytest`.
 
-1. Install the test dependencies (into the virtual environment where you installed PyGambit): ::
-
-    pip install -r tests/requirements.txt
-
-2. Navigate to the Gambit repository and run the tests: ::
+1. Ensure `pygambit` is installed with test dependencies: see :ref:`build-python`.
 
-    pytest
+2. Run pytest: ::
 
-3. [Optional] If you wish to run the tutorial notebook tests, you will need to add the ``--run-tutorials`` flag, which require the `doc` dependencies: ::
-
-    pip install -r doc/requirements.txt
     pytest --run-tutorials
 
+.. tip::
+    You can omit the `--run-tutorials` to skip running the tutorial notebook tests which take longest to run.
+    Running tests including tutorials requires `doc` as well as `test` dependencies; see :ref:`build-python`.
+
 Adding to the test suite
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -134,9 +133,7 @@ You can also build the documentation locally to preview your changes before subm
 
 1. `Install Pandoc <https://pandoc.org/installing.html>`_ for your OS
 
-2. Install the docs dependencies (into the virtual environment where you installed PyGambit): ::
-
-    pip install -r doc/requirements.txt
+2. Ensure `pygambit` is installed with doc dependencies: see :ref:`build-python`.
 
 3. Navigate to the Gambit repo and build the docs: ::
 
@@ -156,7 +153,7 @@ To submit a tutorial for inclusion in the Gambit documentation, please follow th
 
 3. Update `doc/pygambit.rst` to ensure the tutorial is listed in the docs at an appropriate location.
 
-4. *[Optional]* If your tutorial requires additional dependencies not already listed in `doc/requirements.txt`, please add them to the file.
+4. *[Optional]* If your tutorial requires additional dependencies not already listed in the ``doc`` list under ``[project.optional-dependencies]`` inside ``pyproject.toml``, please add them to the file.
 
 
 Recognising contributions

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