Added ReadtheDocs documentation for the public API

- Reformatted the docstring to be compatible
- Added tests to make sure the documentation compiles properly
- Added sphinx as a pip requirement

Co-authored-by: Philip Paquette <pcpaquette@gmail.com>
Co-authored-by: notoraptor <stevenbocco@gmail.com>

1 files changed, 19 insertions, 6 deletions

diff --git a/diplomacy/integration/webdiplomacy_net/api.py b/diplomacy/integration/webdiplomacy_net/api.py
index b4bde01..36b132c 100644
--- a/diplomacy/integration/webdiplomacy_net/api.py
+++ b/diplomacy/integration/webdiplomacy_net/api.py
@@ -39,8 +39,10 @@ class API(BaseAPI):
 
     @gen.coroutine
     def list_games_with_players_in_cd(self):
-        """ Lists the game on the standard map where a player is in CD and the bots needs to submit orders
-            :return: List of GameIdCountryId tuples  [(game_id, country_id), (game_id, country_id)]
+        """ Lists the game on the standard map where a player is in CD (civil disorder)
+            and the bots needs to submit orders
+
+            :return: List of :class:`.GameIdCountryId` tuples  [(game_id, country_id), (game_id, country_id)]
         """
         route = 'players/cd'
         url = '%s?%s' % (API_WEBDIPLOMACY_NET, urlencode({'route': route}))
@@ -73,7 +75,8 @@ class API(BaseAPI):
     @gen.coroutine
     def list_games_with_missing_orders(self):
         """ Lists of the game on the standard where the user has not submitted orders yet.
-            :return: List of GameIdCountryId tuples  [(game_id, country_id), (game_id, country_id)]
+
+            :return: List of :class:`.GameIdCountryId` tuples  [(game_id, country_id), (game_id, country_id)]
         """
         route = 'players/missing_orders'
         url = '%s?%s' % (API_WEBDIPLOMACY_NET, urlencode({'route': route}))
@@ -106,13 +109,19 @@ class API(BaseAPI):
     @gen.coroutine
     def get_game_and_power(self, game_id, country_id, max_phases=None):
         """ Returns the game and the power we are playing
+
             :param game_id: The id of the game object (integer)
             :param country_id: The id of the country for which we want the game state (integer)
             :param max_phases: Optional. If set, improve speed by generating game only using the last 'x' phases.
+            :type game_id: int
+            :type country_id: int
+            :type max_phases: int | None, optional
             :return: A tuple consisting of
-                    1) The diplomacy.Game object from the game state or None if an error occurred
-                    2) The power name (e.g. 'FRANCE') referred to by country_id
+
+                #. The diplomacy.Game object from the game state or None if an error occurred
+                #. The power name (e.g. 'FRANCE') referred to by country_id
         """
+        # pylint: disable=arguments-differ
         route = 'game/status'
         url = '%s?%s' % (API_WEBDIPLOMACY_NET, urlencode({'route': route, 'gameID': game_id, 'countryID': country_id}))
         return_val = None, None
@@ -144,12 +153,16 @@ class API(BaseAPI):
     @gen.coroutine
     def set_orders(self, game, power_name, orders, wait=None):
         """ Submits orders back to the server
-            :param game: A diplomacy.Game object representing the current state of the game
+
+            :param game: A :class:`diplomacy.engine.game.Game` object representing the current state of the game
             :param power_name: The name of the power submitting the orders (e.g. 'FRANCE')
             :param orders: A list of strings representing the orders (e.g. ['A PAR H', 'F BRE - MAO'])
             :param wait: Optional. If True, sets ready=False, if False sets ready=True.
             :return: True for success, False for failure
             :type game: diplomacy.Game
+            :type power_name: str
+            :type orders: List[str]
+            :type wait: bool | None, optional
         """
         # Logging orders
         LOGGER.info('[%s/%s/%s] - Submitting orders: %s', game.game_id, game.get_current_phase(), power_name, orders)