.. _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

.. note::

   When updating the catalog, changes can be viewed by inspecting the documentation build generated by a pull request.
   To test changes locally, you'll need to have a developer install of `pygambit` available in your Python environment, see :ref:`build-python`.

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. **Commit the changes:**

   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")

3. **[Optional] Test your updates locally (and customise visuals):**

   Reinstall the package to pick up the new game file(s) in the ``pygambit.catalog`` module.
   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, you can first edit the ``catalog_draw_tree_settings`` in ``build_support/catalog/update.py`` to change the default visualisation parameters for your game(s).
   Consult the `DrawTree docs <https://www.gambit-project.org/draw_tree/>`_ for the available options.

   .. code-block:: bash

       pip install .
       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::

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

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

   .. important::

      If you didn't run the update script in step 3, you should manually update ``EXTRA_DIST`` in ``Makefile.am`` with any new game files.


Adding games from external libraries
------------------------------------

You can use the catalog update script to pull games from external libraries by providing the appropriate flags.

OpenSpiel_
^^^^^^^^^^

.. _OpenSpiel: https://openspiel.readthedocs.io/en/latest/games.html

.. code-block:: bash

    python build_support/catalog/generate_openspiel.py

.. important::

   If any games are added or changed by running this script, you'll need to run the ``update.py`` script as per step 3 above.