improve docstring handling for catalog API docs

Author: edwardchalstrey1

src/pygambit/catalog.py

@@ -31,7 +31,11 @@ def __new__(cls, *args, **kwargs) -> gbt.Game:
 
     @staticmethod
     def _game() -> gbt.Game:
-        """Override this method in subclasses to define the game."""
+        """
+        Examples
+        --------
+        >>> {classname}()  # Gets the game instance
+        """
         raise NotImplementedError("Subclasses must implement _game() method")
 
     @classmethod
@@ -40,6 +44,14 @@ def _extract_description(cls, game: gbt.Game) -> None:
         cleaned_docstring = ""
         if cls.__doc__:
             cleaned_docstring = inspect.cleandoc(cls.__doc__)
+            # If the class has a _game function, concatenate its docstring to the class docstring
+            game_docstring = inspect.getdoc(cls._game)
+            if game_docstring:
+                game_docstring = inspect.cleandoc(game_docstring)
+            # For games from file, sub in the class name
+            game_docstring = game_docstring.replace("{classname}", cls.__name__)
+            cleaned_docstring += "\n\n" + game_docstring
+            cls.__doc__ = cleaned_docstring
         if len(cleaned_docstring) > 0:
             game.description = cleaned_docstring
 

src/pygambit/catalog_games.py

@@ -26,6 +26,11 @@ def _game(unique_NE_variant: bool = False):
         -------
         gbt.Game
             The constructed extensive-form game.
+
+        Examples
+        --------
+        >>> OneShotTrust._game(unique_NE_variant=False) # Constructs the standard game
+        >>> OneShotTrust._game(unique_NE_variant=True) # Constructs the game with unique NE variant
         """
         g = gbt.Game.new_tree(
             players=["Buyer", "Seller"], title="One-shot trust game, after Kreps (1990)"

tests/test_catalog.py

@@ -39,7 +39,10 @@ def test_custom_game_subclass_extracts_metadata(self):
 
     def test_can_get_game_description_from_docstring(self):
         """CatalogGame should get description from docstring over game description."""
-        assert ExampleGameWithDocstring().description == "Alternative test game description."
+        assert (
+            "Alternative test game description." in
+            ExampleGameWithDocstring().description
+        )
 
     def test_catalog_py_game_with_parameters(self):
         """
@@ -56,8 +59,8 @@ def test_catalog_yml_game_instantiation(self):
     def test_catalog_yml_game_description(self):
         """Custom CatalogGame subclasses reading from catalog.yml should return Game instances."""
         assert (
+            "A simple implementation of a two person Prisoner's Dilemma game." in
             gbt.catalog.PrisonersDilemma().description
-            == "A simple implementation of a two person Prisoner's Dilemma game."
         )