.. _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>`.
   Use a full link to the bibliography entry, so the link can be accessed from the file directly, as well as being rendered in the docs e.g. ```Rei2008 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Rei2008>`_``

   .. important::

      If no bibliography entry exists, you should add one by editing `doc/biblio.rst`.

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.
   If there are multiple games from a particular source, place them in an appropriately named folder.

   .. important::

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

      .. code-block:: python

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

   .. note::

      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.

      **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__wide.ef    # additional (tab label "Wide")

      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. ``__very_wide`` → "Very Wide").

3. **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``.

4. **[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.

5. **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.