Fix documentation

Author: MarcCote

docs/requirements.txt

@@ -1,6 +1,6 @@
 -r ../requirements.txt
-sphinx>=2
+sphinx>=2,<=5.1.1
 recommonmark
 sphinx_autodoc_typehints
 sphinx-argparse
--e git://github.com/snide/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
+sphinx-rtd-theme

docs/source/conf.py

@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -106,7 +106,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/source/notes/zork1.md

@@ -3,8 +3,9 @@ Some notes about Zork1.
 
 ## Stochasticity
 Zork1 has some stochasticity in it:
- - the thief will wander randomly in the dungeon stealing stuff.
- - when attacking someone, you can miss (to confirm)
+
+  - the thief will wander randomly in the dungeon stealing stuff.
+  - when attacking someone, you can miss (to confirm)
 
 ## Death
 It seems that when you died, you get to continue playing but you lose 10 points (I think it is always 10). However, on your third death, the game ends.

textworld/generator/chaining.py

@@ -89,13 +89,9 @@ class ChainingOptions:
             Whether to allow totally independent parallel chains.
         create_variables:
             Whether new variables may be created during chaining.
-        fixed_mapping:
-            A fixed mapping from placeholders to variables, for singletons.
         rng:
             If provided, randomize the order of the quests using this random
             number generator.
-        logic:
-            The rules of the game.
         rules_per_depth:
             A list of lists of rules for restricting the allowed actions at
             certain depths.
@@ -124,10 +120,12 @@ def __init__(self):
 
     @property
     def logic(self) -> GameLogic:
+        """ The rules of the game. """
         return self.kb.logic
 
     @property
     def fixed_mapping(self) -> GameLogic:
+        """ A fixed mapping from placeholders to variables, for singletons. """
         return self.kb.types.constants_mapping
 
     def get_rules(self, depth: int) -> Iterable[Rule]:

textworld/generator/game.py

@@ -64,11 +64,6 @@ class Event:
 
     An event gets triggered when its set of conditions become all statisfied.
 
-    Attributes:
-        actions: Actions to be performed to trigger this event
-        commands: Human readable version of the actions.
-        condition: :py:class:`textworld.logic.Action` that can only be applied
-                    when all conditions are statisfied.
     """
 
     def __init__(self, actions: Iterable[Action] = (),
@@ -85,18 +80,23 @@ def __init__(self, actions: Iterable[Action] = (),
         """
         self.actions = actions
         self.commands = commands
+
+        #: :py:class:`textworld.logic.Action`: Action that can only be applied
+        #:  when all conditions are statisfied.
         self.condition = self.set_conditions(conditions)
 
     @property
-    def actions(self) -> Iterable[Action]:
+    def actions(self) -> Tuple[Action]:
+        """ Actions to perform to trigger this event. """
         return self._actions
 
     @actions.setter
     def actions(self, actions: Iterable[Action]) -> None:
         self._actions = tuple(actions)
 
     @property
-    def commands(self) -> Iterable[str]:
+    def commands(self) -> Tuple[str]:
+        """ Human readable version of the actions. """
         return self._commands
 
     @commands.setter
@@ -177,18 +177,6 @@ class Quest:
     A quest is defined by a mutually exclusive set of winning events and
     a mutually exclusive set of failing events.
 
-    Attributes:
-        win_events: Mutually exclusive set of winning events. That is,
-                    only one such event needs to be triggered in order
-                    to complete this quest.
-        fail_events: Mutually exclusive set of failing events. That is,
-                     only one such event needs to be triggered in order
-                     to fail this quest.
-        reward: Reward given for completing this quest.
-        desc: A text description of the quest.
-        commands: List of text commands leading to this quest completion.
-        optional: Whether this quest is optional or not to finish the game.
-        repeatable: Whether this quest can be completed more than once.
     """
 
     def __init__(self,
@@ -217,13 +205,18 @@ def __init__(self,
         """
         self.win_events = tuple(win_events)
         self.fail_events = tuple(fail_events)
+
+        #: str: A text description of the quest.
         self.desc = desc
         self.commands = tuple(commands)
+        #: bool: Whether this quest is optional or not to finish the game.
         self.optional = optional
+        #: bool: Whether this quest can be completed more than once.
         self.repeatable = repeatable
         if self.repeatable:
             assert self.optional  # Only optional quest can be repeatable.
 
+        #: int: Reward given for completing this quest.
         # Unless explicitly provided, reward is set to 1 if there is at least
         # one winning events otherwise it is set to 0.
         self.reward = int(len(win_events) > 0) if reward is None else reward
@@ -232,15 +225,23 @@ def __init__(self,
             raise UnderspecifiedQuestError()
 
     @property
-    def win_events(self) -> Iterable[Event]:
+    def win_events(self) -> Tuple[Event]:
+        """ Mutually exclusive set of winning events. That is,
+            only one such event needs to be triggered in order
+            to complete this quest.
+        """
         return self._win_events
 
     @win_events.setter
     def win_events(self, events: Iterable[Event]) -> None:
         self._win_events = tuple(events)
 
     @property
-    def fail_events(self) -> Iterable[Event]:
+    def fail_events(self) -> Tuple[Event]:
+        """ Mutually exclusive set of failing events. That is,
+            only one such event needs to be triggered in order
+            to fail this quest.
+        """
         return self._fail_events
 
     @fail_events.setter
@@ -249,6 +250,7 @@ def fail_events(self, events: Iterable[Event]) -> None:
 
     @property
     def commands(self) -> Iterable[str]:
+        """ List of text commands leading to this quest completion. """
         return self._commands
 
     @commands.setter
@@ -297,8 +299,8 @@ def deserialize(cls, data: Mapping) -> "Quest":
     def serialize(self) -> Mapping:
         """ Serialize this quest.
 
-        Results:
-            Quest's data serialized to be JSON compatible
+        Returns:
+            Quest's data serialized to be JSON compatible.
         """
         data = {}
         data["desc"] = self.desc
@@ -370,8 +372,8 @@ def deserialize(cls, data: Mapping) -> "EntityInfo":
     def serialize(self) -> Mapping:
         """ Serialize this object.
 
-        Results:
-            EntityInfo's data serialized to be JSON compatible
+        Returns:
+            EntityInfo's data serialized to be JSON compatible.
         """
         return {slot: getattr(self, slot) for slot in self.__slots__}
 
@@ -1071,11 +1073,6 @@ class GameOptions:
             Number of objects in the game.
         nb_parallel_quests (int):
             Number of parallel quests, i.e. not sharing a common goal.
-        quest_length (int):
-            Number of actions that need to be performed to complete the game.
-        quest_breadth (int):
-            Number of subquests per independent quest. It controls how nonlinear
-            a quest can be (1: linear).
         quest_depth (int):
             Number of actions that need to be performed to solve a subquest.
         path (str):
@@ -1086,27 +1083,6 @@ class GameOptions:
         file_ext (str):
             Type of the generated game file. Either .z8 (Z-Machine) or .ulx (Glulx).
             If `path` already has an extension, this is ignored.
-        seeds (Optional[Union[int, Dict]]):
-            Seeds for the different generation processes.
-
-               * If `None`, seeds will be sampled from
-                 :py:data:`textworld.g_rng <textworld.utils.g_rng>`.
-               * If `int`, it acts as a seed for a random generator that will be
-                 used to sample the other seeds.
-               * If dict, the following keys can be set:
-
-                 * `'map'`: control the map generation;
-                 * `'objects'`: control the type of objects and their
-                   location;
-                 * `'quest'`: control the quest generation;
-                 * `'grammar'`: control the text generation.
-
-                 For any key missing, a random number gets assigned (sampled
-                 from :py:data:`textworld.g_rng <textworld.utils.g_rng>`).
-        kb (KnowledgeBase):
-            The knowledge base containing the logic and the text grammars (see
-            :py:class:`textworld.generator.KnowledgeBase <textworld.generator.data.KnowledgeBase>`
-            for more information).
         chaining (ChainingOptions):
             For customizing the quest generation (see
             :py:class:`textworld.generator.ChainingOptions <textworld.generator.chaining.ChainingOptions>`
@@ -1132,6 +1108,7 @@ def __init__(self):
 
     @property
     def quest_length(self) -> int:
+        """ Number of actions that need to be performed to complete the game. """
         assert self.chaining.min_length == self.chaining.max_length
         return self.chaining.min_length
 
@@ -1143,6 +1120,9 @@ def quest_length(self, value: int) -> None:
 
     @property
     def quest_breadth(self) -> int:
+        """ Number of subquests per independent quest. It controls how nonlinear
+            a quest can be (1 means linear).
+        """
         assert self.chaining.min_breadth == self.chaining.max_breadth
         return self.chaining.min_breadth
 
@@ -1153,6 +1133,23 @@ def quest_breadth(self, value: int) -> None:
 
     @property
     def seeds(self):
+        """ Seeds for the different generation processes.
+
+               * If `None`, seeds will be sampled from
+                 :py:data:`textworld.g_rng <textworld.utils.g_rng>`.
+               * If `int`, it acts as a seed for a random generator that will be
+                 used to sample the other seeds.
+               * If dict, the following keys can be set:
+
+                 * `'map'`: control the map generation;
+                 * `'objects'`: control the type of objects and their
+                   location;
+                 * `'quest'`: control the quest generation;
+                 * `'grammar'`: control the text generation.
+
+                 For any key missing, a random number gets assigned (sampled
+                 from :py:data:`textworld.g_rng <textworld.utils.g_rng>`).
+        """
         if self._seeds is None:
             self.seeds = {}  # Generate seeds from g_rng.
 
@@ -1190,6 +1187,10 @@ def rngs(self) -> Dict[str, RandomState]:
 
     @property
     def kb(self) -> KnowledgeBase:
+        """ The knowledge base containing the logic and the text grammars (see
+            :py:class:`textworld.generator.KnowledgeBase <textworld.generator.data.KnowledgeBase>`
+            for more information).
+        """
         if self._kb is None:
             self.kb = KnowledgeBase.load()