.. _updating-catalog:

Updating the Games Catalog
==========================

This page includes developer notes regarding the catalog module, and the process for contributing to and updating Gambit's :ref:`Games Catalog <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 new games to the catalog, or edit existing ones that are saved in a valid representation :ref:`format <file-formats>`.
Currently supported representations are:

- `.efg` for extensive form games
- `.nfg` for normal form games

.. important::

   When updating the catalog, changes can be viewed by inspecting the documentation build generated by a pull request.
   You can also test changes locally. It can be helpful when doing so to perform an editable install of `pygambit` available in your Python environment.
   Note that for general edits to the codebase non-editable :ref:`developer install <build-python>` is better to pick up changes in the C++ code as well as Python.

   .. code-block:: bash

      pip install -e ".[doc]"

1. **Create or edit a game file:**

   Use either :ref:`pygambit <pygambit>`, the Gambit :ref:`CLI <command-line>` or :ref:`GUI <section-gui>` to create (or edit) and save game in a valid representation :ref:`format <file-formats>`.
   Make sure the game includes a description, with any citations referencing the :ref:`bibliography <bibliography>` using the ``:cite:p:`key``` format, e.g. ``:cite:p:`Rei2008```.

   .. important::

      If no bibliography entry exists, you should add one. For instructions,
      see :ref:`updating-bibliography`.

2. **Add the game(s) to the repo:**

   Create a new branch in the ``gambit`` repo.
   Add your new game file(s) inside the ``catalog`` dir and commit them, or edit an existing game.
   The catalog uses a hierarchical folder structure that groups games by publication type and venue:

   .. code-block:: text

      catalog/
        books/{author-year}/{game}.efg       # games from textbooks
        journals/{venue}/{author-year}/{game}.efg  # games from journals (venue = geb, ijgt, mor, …)
        conf/{venue}/{author-year}/{game}.efg      # games from conferences

   The folder path determines the game's slug, used by the load function:

   .. code-block:: python

      pygambit.catalog.load("books/watson2013/exercise29_6")
      pygambit.catalog.load("journals/geb/bagwell1995")

   .. note::

      When adding a game from a **new** journal, conference, or other top-level category,
      add a human-readable label for the new hierarchy node(s) to
      ``build_support/catalog/catalog_hierarchy.yaml``.
      The catalog documentation page groups and labels games based on this file.
      Nodes without an entry fall back to a title-cased version of the folder name.

   .. important::

      The name of the game file will determine its "slug", used by the load function of the catalog module:

      .. code-block:: python

         pygambit.catalog.load("books/watson2013/exercise29_6")

3. **[Optional] Add custom game layout(s):**

   For extensive form games, you may optionally commit a curated ``.ef`` file alongside the ``.efg``
   (e.g. ``catalog/source/game.ef``).
   When present, ``update.py`` will use this file directly as input to DrawTree instead of
   auto-generating the layout from the ``.efg``, preserving any hand-tuned layout.
   Consult the `DrawTree docs <https://www.gambit-project.org/draw_tree/>`_ for the ``.ef`` format.

   In general, ``.ef`` files should only be added when the layout they provide differs significantly
   from what DrawTree produces automatically; if the auto-generated layout is reasonable, there is
   no need to include one.

   If the game has an original layout from a published source (e.g. a textbook or journal article),
   you **should** try to capture that layout in an ``.ef`` file — you can create it manually or
   try passing the ``.ef`` format spec and a screenshot of the original to an AI to generate it.

   **Layout variants:** To display multiple layout variants on the catalog page (rendered as
   clickable tabs), commit additional ``.ef`` files using the ``{slug}__{label}.ef`` naming
   convention (double underscore separator), e.g.:

   .. code-block:: text

      catalog/example/game.ef                     # primary (tab label "Default")
      catalog/example/game__original_layout.ef    # additional (tab label "Original Layout")

   The label shown on each tab is derived automatically from the filename suffix: underscores
   are replaced by spaces and the result is title-cased (e.g. ``__alt_version`` → "Alt Version").

4. **Update the build files:**

   Ensure you have installed the package in editable mode to automatically pick up the new game file(s) in the ``pygambit.catalog`` module without reinstalling each time.
   Then use the ``update.py`` script to update Gambit's documentation & build files, as well as generating images for the new game(s).
   If you want to customise the visualisation parameters for your game(s), edit ``build_support/catalog/draw_tree_settings.yaml``.
   Add an entry under ``overrides`` keyed by your game's exact slug, or by a shared prefix (e.g. the author-year folder name) to apply settings to all games from that source.
   More specific entries (longer keys) take precedence over shorter ones.
   Consult the `DrawTree docs <https://www.gambit-project.org/draw_tree/>`_ for available settings.

   .. code-block:: bash

       python build_support/catalog/update.py --build

   .. note::

      You can use the ``--regenerate-images`` flag when building the docs locally for a second time to force any changes to be picked up.

   .. warning::

      - If haven't done an editable install of ``pygambit`` in your python environment, you'll need to re-install it before running the update script to include new games in the catalog module.
      - Running the script with the ``--build`` flag updates ``build_support/catalog/catalog.am``, which is included in ``Makefile.am``. If you moved games that were previously in ``contrib/games`` you'll need to also manually remove those files from ``EXTRA_DIST`` in ``Makefile.am``.

   .. tip::

      If you encounter any issues with game files in your python environment not matching the current branch preventing the update script or docs build working (step below) try running the following first:

      .. code-block:: bash

          git clean -fdX catalog/img doc/catalog_table.rst

   .. tip::

      If the game visuals for extensive form games need some work and you aren't sure which settings to change in ``build_support/catalog/draw_tree_settings.yaml``, try loading the EFG in the DrawTree GUI and adjusting the layout there.
      There is an option to `download settings <https://www.gambit-project.org/draw_tree/gui/#exporting-and-reusing-settings>`_ which can be used in the Gambit catalog.

5. **[Optional] Test your updates to the documentation locally:**

   The previous step will (re)build your local copy of the Gambit Catalog RST page used by the documentation.
   You should then build the docs in the :ref:`usual way <editing-docs>`.
   Open the catalog page at ``doc/_build/html/catalog.html`` to view your changes.
   Iterate steps 2-4 as required.

6. **Submit a pull request to GitHub with all changes.**

   Submit a PR according to the :ref:`usual workflow <submit-contribution>`.
   Ensure that any additions and changes to game files, ``build_support/catalog/draw_tree_settings.yaml``, ``build_support/catalog/update.py`` and ``build_support/catalog/catalog.am`` are included.

   .. important::

      Even if you already checked the local docs build, ensure the Catalog page on the ReadTheDocs preview build on the pull request looks right.