From 60cd7b29693786ca8bb7e61c4c80a7249fb945c0 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 14:37:29 +0100 Subject: [PATCH 1/6] docs: update catalog layout guidelines --- doc/developer.catalog.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index 68f0f442e..a70a217ee 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -77,17 +77,25 @@ Currently supported representations are: auto-generating the layout from the ``.efg``, preserving any hand-tuned layout. Consult the `DrawTree docs `_ 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__wide.ef # additional (tab label "Wide") + 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. ``__very_wide`` → "Very Wide"). + are replaced by spaces and the result is title-cased (e.g. ``__alt_version`` → "Alt Version"). 3. **Update the build files:** From 179f7dacfab8c92648358c23dcec375d01dc40d9 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 14:39:40 +0100 Subject: [PATCH 2/6] Refactor game layout to an optional step --- doc/developer.catalog.rst | 46 +++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index a70a217ee..a8f62be7b 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -69,35 +69,35 @@ Currently supported representations are: pygambit.catalog.load("books/watson2013/exercise29_6") - .. note:: +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 `_ for the ``.ef`` format. + 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 `_ 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. + 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. + 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.: + **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 + .. code-block:: text - catalog/example/game.ef # primary (tab label "Default") - catalog/example/game__original_layout.ef # additional (tab label "Original Layout") + 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"). + 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"). -3. **Update the build files:** +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). @@ -119,14 +119,14 @@ Currently supported representations are: - 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:** +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 `. 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.** +6. **Submit a pull request to GitHub with all changes.** Submit a PR according to the :ref:`usual workflow `. 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. From ddf7266f88db74ccf5762e07e58e1800988b7232 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 15:03:30 +0100 Subject: [PATCH 3/6] Add tip --- doc/developer.catalog.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index a8f62be7b..6b66dd99e 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -119,6 +119,14 @@ Currently supported representations are: - 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 (step below) try running the following first: + + .. code-block:: bash + + git clean -fdX catalog/img doc/catalog_table.rst + 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. From 3fa2231dee4256b84f041b7277385457880e03fb Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 15:04:18 +0100 Subject: [PATCH 4/6] tiny fix --- doc/developer.catalog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index 6b66dd99e..19933dd3f 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -121,7 +121,7 @@ Currently supported representations are: .. 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 (step below) try running the following first: + 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 From 2d7999b1e88bc52b7599a262e3ead23d326cb8bf Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 15:09:04 +0100 Subject: [PATCH 5/6] docs: add developer tips for extensive form game visuals --- doc/developer.catalog.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index 19933dd3f..747e367f2 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -127,6 +127,11 @@ Currently supported representations are: 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. From 2adcc9690d4c381b3cad3d603f69be9443693998 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 17 Jun 2026 15:10:26 +0100 Subject: [PATCH 6/6] docs: fix a broken link in developer.catalog.rst --- doc/developer.catalog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/developer.catalog.rst b/doc/developer.catalog.rst index 747e367f2..c37c8b567 100644 --- a/doc/developer.catalog.rst +++ b/doc/developer.catalog.rst @@ -130,7 +130,7 @@ Currently supported representations are: .. 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. + There is an option to `download settings `_ which can be used in the Gambit catalog. 5. **[Optional] Test your updates to the documentation locally:**