Merge pull request #267 from MarcCote/doc_tw_cooking

Add documentation for tw-cooking challenge.

Author: MarcCote

docs/source/index.rst

@@ -22,6 +22,15 @@ TextWorld is a text-based learning environment for Reinforcement Learning agent.
    tw-view
    tw-extract
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Challenges:
+
+   textworld.challenges.simple
+   textworld.challenges.coin_collector
+   textworld.challenges.cooking
+   textworld.challenges.treasure_hunter
+
 .. toctree::
    :maxdepth: 1
    :caption: Package:

docs/source/textworld.challenges.coin_collector.rst

@@ -0,0 +1,11 @@
+.. automodule:: textworld.challenges.coin_collector
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    Usage
+    -----
+    .. argparse::
+        :ref: textworld.challenges.tw_coin_collector.coin_collector.build_argparser
+        :prog: tw-make tw-coin_collector
+        :markdownhelp:

docs/source/textworld.challenges.cooking.rst

@@ -0,0 +1,11 @@
+.. automodule:: textworld.challenges.cooking
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    Usage
+    -----
+    .. argparse::
+        :ref: textworld.challenges.tw_cooking.cooking.build_argparser
+        :prog: tw-make tw-cooking
+        :markdownhelp:

docs/source/textworld.challenges.rst

@@ -1,22 +1,10 @@
 textworld.challenges
 ====================
 
-.. automodule:: textworld.challenges
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. toctree::
+    :maxdepth: 1
 
-.. automodule:: textworld.challenges.coin_collector
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: textworld.challenges.treasure_hunter
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: textworld.challenges.simple
-    :members:
-    :undoc-members:
-    :show-inheritance:
+    textworld.challenges.simple
+    textworld.challenges.coin_collector
+    textworld.challenges.cooking
+    textworld.challenges.treasure_hunter

docs/source/textworld.challenges.simple.rst

@@ -0,0 +1,13 @@
+
+
+.. automodule:: textworld.challenges.simple
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    Usage
+    -----
+    .. argparse::
+        :ref: textworld.challenges.tw_simple.simple.build_argparser
+        :prog: tw-make tw-simple
+        :markdownhelp:

docs/source/textworld.challenges.treasure_hunter.rst

@@ -0,0 +1,11 @@
+.. automodule:: textworld.challenges.treasure_hunter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    Usage
+    -----
+    .. argparse::
+        :ref: textworld.challenges.tw_treasure_hunter.treasure_hunter.build_argparser
+        :prog: tw-make tw-treasure_hunter
+        :markdownhelp:

scripts/tw-make

@@ -150,6 +150,10 @@ if __name__ == "__main__":
     parser, custom_parser, challenge_parsers = build_parser(default_parser_only=False)
     args = parser.parse_args()
 
+    if args.subcommand is None:
+        print("Need to specify which type of game to create (either 'custom' or a challenge).")
+        exit_listing_challenges(args.subcommand)
+
     if args.seed is None:
         args.seed = np.random.randint(65635)
 

textworld/challenges/tw_cooking/cooking.py

@@ -14,34 +14,6 @@
 eat it. To control the game's difficulty, one can specify the amount of skills
 that are involved to solve it (see skills section below).
 
-Skills
-------
-    The required skills are:
-
-    * recipe{1,2,3} : Number of ingredients in the recipe.
-
-    The optional skills that can be combined are:
-
-    * take{1,2,3} : Number of ingredients to fetch. It must be less
-      or equal to the value of the `recipe` skill.
-    * open : Whether containers/doors need to be opened.
-    * cook : Whether some ingredients need to be cooked.
-    * cut : Whether some ingredients need to be cut.
-    * drop : Whether the player's inventory has limited capacity.
-    * go{1,6,9,12} : Number of locations in the game.
-
-
-Splits
-------
-    In addition to the skills, one can specify from which disjoint distribution
-    the game should be generated from:
-
-    * train : game use for training agent;
-    * valid : game may contain food items (adj-noun pairs) unseen within
-      the train split. It can also contain unseen food preparation;
-    * test : game may contain food items (adj-noun pairs) unseen within
-      the train split. It can also contain unseen food preparation.
-
 References
 ----------
 .. [1] https://aka.ms/ftwp
@@ -1317,7 +1289,7 @@ def _place_one_distractor(candidates, ingredient):
 def build_argparser(parser=None):
     parser = parser or argparse.ArgumentParser()
 
-    group = parser.add_argument_group('First TextWorld Competition game settings')
+    group = parser.add_argument_group('The Cooking Game settings')
     group.add_argument("--recipe", type=int, default=1, metavar="INT",
                        help="Number of ingredients in the recipe. Default: %(default)s")
     group.add_argument("--take", type=int, default=0, metavar="INT",
@@ -1337,9 +1309,12 @@ def build_argparser(parser=None):
                        help="Random seed used for generating the recipe. Default: %(default)s")
 
     group.add_argument("--split", choices=["train", "valid", "test"],
-                       help="Control which foods can be used. Can either be"
-                            " 'train', 'valid', or 'test'."
-                            " Default: foods from all dataset splits can be used.")
+                       help="Specify the game distribution to use. Food items (adj-noun pairs) are split in three subsets."
+                            " Also, the way the training food items can be prepared is further divided in three subsets.\n\n"
+                            "* train: training food and their corresponding training preparations\n"
+                            "* valid: valid food + training food but with unseen valid preparations\n"
+                            "* test: test food + training food but with unseen test preparations\n\n"
+                            " Default: game is drawn from the joint distribution over train, valid, and test.")
 
     return parser