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>

4 files changed, 58 insertions, 47 deletions

diff --git a/diplomacy/integration/base_api.py b/diplomacy/integration/base_api.py
index c0dca4e..584310b 100644
--- a/diplomacy/integration/base_api.py
+++ b/diplomacy/integration/base_api.py
@@ -28,9 +28,13 @@ class BaseAPI(metaclass=ABCMeta):
 
     def __init__(self, api_key, connect_timeout=30, request_timeout=60):
         """ Constructor
+
             :param api_key: The API key to use for sending API requests
             :param connect_timeout: The maximum amount of time to wait for the connection to be established
             :param request_timeout: The maximum amount of time to wait for the request to be processed
+            :type api_key: str
+            :type connect_timeout: int, optional
+            :type request_timeout: int, optional
         """
         self.api_key = api_key
         self.http_client = AsyncHTTPClient()
@@ -39,30 +43,14 @@ class BaseAPI(metaclass=ABCMeta):
 
     @gen.coroutine
     @abstractmethod
-    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)]
-        """
-        raise NotImplementedError()
-
-    @gen.coroutine
-    @abstractmethod
-    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)]
-        """
-        raise NotImplementedError()
-
-    @gen.coroutine
-    @abstractmethod
-    def get_game_and_power(self, game_id, country_id, max_phases=None):
+    def get_game_and_power(self, *args, **kwargs):
         """ 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.
+            *Arguments are specific to each implementation.*
+
             :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 or None if an error occurred
+                #. The power name (e.g. 'FRANCE')
         """
         raise NotImplementedError()
 
@@ -70,6 +58,7 @@ class BaseAPI(metaclass=ABCMeta):
     @abstractmethod
     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 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'])
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)
diff --git a/diplomacy/integration/webdiplomacy_net/game.py b/diplomacy/integration/webdiplomacy_net/game.py
index 0233ea9..a89933c 100644
--- a/diplomacy/integration/webdiplomacy_net/game.py
+++ b/diplomacy/integration/webdiplomacy_net/game.py
@@ -18,9 +18,7 @@ LOGGER = logging.getLogger(__name__)
 
 
 def turn_to_phase(turn, phase):
-    """ Converts a turn and phase to a short phase name
-        e.g. turn 1 - phase 'Retreats' to 'F1901R'
-    """
+    """ Converts a turn and phase to a short phase name e.g. turn 1 - phase 'Retreats' to 'F1901R' """
     year = 1901 + turn // 2
     season = 'S' if turn % 2 == 0 else 'F'
     if phase == 'Builds':
@@ -36,13 +34,14 @@ def turn_to_phase(turn, phase):
 #  'retreating': 'Yes'/'No'}
 def unit_dict_to_str(unit_dict, map_id=1):
     """ Converts a unit from the dictionary format to the string format
-        e.g. {'unitType': 'Army', 'terrID': 6, 'countryId': 1, 'retreating': 'No'}
-             to 'ENGLAND', 'A LON'
+        e.g. ``{'unitType': 'Army', 'terrID': 6, 'countryId': 1, 'retreating': 'No'}``
+        to ``'ENGLAND', 'A LON'``
 
         :param unit_dict: The unit in dictionary format from webdiplomacy.net
         :return: A tuple consisting of:
-            1) The power owning the unit (e.g. 'FRANCE')
-            2) The unit in string format (with a leading * when dislodged) (e.g. '*A PAR')
+
+            #. The power owning the unit (e.g. 'FRANCE')
+            #. The unit in string format (with a leading ``*`` when dislodged) (e.g. ``'*A PAR'``)
     """
     req_fields = ('unitType', 'terrID', 'countryID', 'retreating')
     if [1 for field in req_fields if field not in unit_dict]:
@@ -84,12 +83,13 @@ def unit_dict_to_str(unit_dict, map_id=1):
 #  'countryId':  integer}
 def center_dict_to_str(center_dict, map_id=1):
     """ Converts a supply center from the dictionary format to the string format
-        e.g. {'terrID': 6, 'countryId': 1} to 'ENGLAND', 'LON'
+        e.g. ``{'terrID': 6, 'countryId': 1}`` to ``'ENGLAND', 'LON'``
 
         :param center_dict: The center in dictionary format from webdiplomacy.net
         :return: A tuple consisting of:
-            1) The power owning the center (e.g. 'FRANCE')
-            2) The location where the supply center is (e.g. 'PAR')
+
+            #. The power owning the center (e.g. 'FRANCE')
+            #. The location where the supply center is (e.g. 'PAR')
     """
     req_fields = ('terrID', 'countryID')
     if [1 for field in req_fields if field not in center_dict]:
@@ -132,11 +132,13 @@ def center_dict_to_str(center_dict, map_id=1):
 #  'dislodged':  'Yes', 'No'}
 def order_dict_to_str(order_dict, phase, map_id=1):
     """ Converts an order from the dictionary format to the string format
+
         :param order_dict: The order in dictionary format from webdiplomacy.net
         :param phase: The current phase ('Diplomacy', 'Retreats', 'Builds')
         :return: A tuple consisting of:
-            1) The power who submitted the order (e.g. 'FRANCE')
-            2) The order in string format (e.g. 'A PAR H')
+
+            #. The power who submitted the order (e.g. 'FRANCE')
+            #. The order in string format (e.g. 'A PAR H')
     """
     req_fields = ('countryID',)
     if [1 for field in req_fields if field not in order_dict]:
@@ -223,12 +225,14 @@ def process_phase_dict(phase_dict, map_id=1):
 #  'standoffs':   []}
 def state_dict_to_game_and_power(state_dict, country_id, max_phases=None):
     """ Converts a game state from the dictionary format to an actual diplomacy.Game object with the related power.
+
         :param state_dict: The game state in dictionary format from webdiplomacy.net
         :param country_id: The country id we want to convert.
         :param max_phases: Optional. If set, improve speed by only keeping the last 'x' phases to regenerate the game.
         :return: A tuple of
-            1) None, None       - on error or if the conversion is not possible, or game is invalid / not-started / done
-            2) game, power_name - on successful conversion
+
+            #. None, None       - on error or if the conversion is not possible, or game is invalid / not-started / done
+            #. game, power_name - on successful conversion
     """
     if state_dict is None:
         return None, None
diff --git a/diplomacy/integration/webdiplomacy_net/orders.py b/diplomacy/integration/webdiplomacy_net/orders.py
index afacf03..8fa966c 100644
--- a/diplomacy/integration/webdiplomacy_net/orders.py
+++ b/diplomacy/integration/webdiplomacy_net/orders.py
@@ -18,9 +18,10 @@ LOGGER = logging.getLogger(__name__)
 
 def is_adjacent_for_convoy(loc_1, loc_2, map_object):
     """ Checks if two locations are adjacent (for convoy purposes)
-            - If loc_1 and loc_2 are water, loc_1 and loc_2 must be adjacent
-            - If loc_1 or loc_2 is land, then they are not adjacent
-            - If loc_1 or loc_2 are coast, then the other locations needs to be a water loc at most 1 loc away
+
+        - If loc_1 and loc_2 are water, loc_1 and loc_2 must be adjacent
+        - If loc_1 or loc_2 is land, then they are not adjacent
+        - If loc_1 or loc_2 are coast, then the other locations needs to be a water loc at most 1 loc away
 
         :type map_object: diplomacy.Map
     """
@@ -48,6 +49,7 @@ def is_adjacent_for_convoy(loc_1, loc_2, map_object):
 
 def find_convoy_path(src, dest, map_object, game=None, including=None, excluding=None):
     """ Finds a convoy path from src to dest
+
         :param src: The source location (e.g. 'BRE')
         :param dest: The destination location (e.g. 'LON')
         :param map_object: A diplomacy.Map object representation of the current map
@@ -55,7 +57,7 @@ def find_convoy_path(src, dest, map_object, game=None, including=None, excluding
         :param including: Optional. A single province (e.g. 'NAO') or a list of provinces that must be in the path.
         :param excluding: Optional. A single province (e.g. 'NAO') or a list of provinces that must NOT be in the path.
         :return: Either an empty list if a convoy is not possible between src and dest
-                 or a list of [src, fleet1, fleet2, ..., fleet_n, dest] to use to convoy A `src` - `dest`.
+             or a list of [src, fleet1, fleet2, ..., fleet_n, dest] to use to convoy A `src` - `dest`.
         :type map_object: diplomacy.Map
         :type game: diplomacy.Game
     """
@@ -122,11 +124,12 @@ def find_convoy_path(src, dest, map_object, game=None, including=None, excluding
     return []
 
 
-class Order():
+class Order:
     """ Class to convert order from string representation to dictionary (webdiplomacy.net) representation """
 
     def __init__(self, order, map_id=None, map_name=None, phase_type=None, game=None):
         """ Constructor
+
             :param order: An order (either as a string 'A PAR H' or as a dictionary)
             :param map_id: Optional. The map id of the map where orders are submitted (webdiplomacy format)
             :param map_name: Optional. The map name of the map where orders are submitted.
@@ -162,6 +165,7 @@ class Order():
 
     def _build_from_string(self, order, game=None):
         """ Builds this object from a string
+
             :type order: str
             :type game: diplomacy.Game
         """
@@ -444,6 +448,7 @@ class Order():
 
     def _build_from_dict(self, order):
         """ Builds this object from a dictionary
+
             :type order: dict
         """
         # pylint: disable=too-many-return-statements