Improve catalog update documentation

doc/developer.catalog.rst

@@ -3,34 +3,51 @@
 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 <pygambit-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'll also need to have a developer install of `pygambit` available in your Python environment, see :ref:`build-python`.
 
-Add new game files
-------------------
-
-You can add games to the catalog saved in a valid representation :ref:`format <file-formats>`.
+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
 
-1. **Create the game file:**
+.. 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`.
 
-   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>`.
+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>`_``
 
-2. **Add the game file:**
+   .. 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::
 
-   Create a new branch in the ``gambit`` repo. Add your new game file(s) inside the ``catalog`` dir and commit them.
+      The name of the game file will determine it's "slug", used by the load function of the catalog module:
 
-3. **Update the catalog:**
+      .. 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
 
@@ -39,32 +56,17 @@ Currently supported representations are:
 
    .. note::
 
-      Update the ``catalog_draw_tree_settings`` in ``build_support/catalog/update.py`` to change the default visualization parameters for your game(s).
-      You can use the ``--regenerate-images`` flag when building the docs locally (readthedocs does this by default).
+      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`.
+      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.
-
-
-Access from pygambit
---------------------
-
-We keep the ``catalog`` directory at the top level of the repository because it is in principle independent
-of the Python and C++ code.  However, in order to include these games with the Python package, there is a bit
-of extra infrastructure.
+   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.
 
-In ``setup.py`` we have a custom build command which first copies the contents of ``catalog/`` into the build
-directory for the Python package.  These are then exposed as data in the ``catalog_data`` directory (changing
-the name to avoid confusion or clashes with ``catalog.py``, which is responsible for accessing the catalog).
+   .. important::
 
-The main implication is that if you are working via the Python package and you add new games to the catalog,
-you will need to rebuild and reinstall the Python extension in order to access the new games.  That is, changing
-the contents of the catalog is no different than changing any other source code in the Python package; you'll
-need to execute ``pip install .`` after the addition or change.
+      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.

doc/developer.contributing.rst

@@ -85,6 +85,7 @@ We recognize that generative AI tools can be a useful aid in software developmen
 - **No AI-generated comments.** Please do not post output from Large Language Models (LLMs) or similar tools as comments on GitHub issues or pull requests. Such comments are often generic and do not add to the discussion.
 - **Humans over bots.** We discourage the use of automated tools, such as bots or agents, to post AI-generated content to issues or pull requests, without the advance approval of the core development team.
 
+.. _submit-contribution:
 
 How to submit a contribution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^