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, 93 insertions, 62 deletions

diff --git a/diplomacy/server/request_managers.py b/diplomacy/server/request_managers.py
index 259147a..073a7ef 100644
--- a/diplomacy/server/request_managers.py
+++ b/diplomacy/server/request_managers.py
@@ -50,6 +50,7 @@ SERVER_GAME_RULES = ['NO_PRESS', 'IGNORE_ERRORS', 'POWER_CHOICE']
 
 def on_clear_centers(server, request, connection_handler):
     """ Manage request ClearCenters.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -64,6 +65,7 @@ def on_clear_centers(server, request, connection_handler):
 
 def on_clear_orders(server, request, connection_handler):
     """ Manage request ClearOrders.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -81,6 +83,7 @@ def on_clear_orders(server, request, connection_handler):
 
 def on_clear_units(server, request, connection_handler):
     """ Manage request ClearUnits.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -95,6 +98,7 @@ def on_clear_units(server, request, connection_handler):
 
 def on_create_game(server, request, connection_handler):
     """ Manage request CreateGame.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -165,6 +169,7 @@ def on_create_game(server, request, connection_handler):
 
 def on_delete_account(server, request, connection_handler):
     """ Manage request DeleteAccount.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -212,6 +217,7 @@ def on_delete_account(server, request, connection_handler):
 
 def on_delete_game(server, request, connection_handler):
     """ Manage request DeleteGame.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -223,21 +229,9 @@ def on_delete_game(server, request, connection_handler):
     server.unschedule_game(level.game)
     Notifier(server, ignore_tokens=[request.token]).notify_game_deleted(level.game)
 
-def on_get_dummy_waiting_powers(server, request, connection_handler):
-    """ Manage request GetAllDummyPowerNames.
-        :param server: server which receives the request.
-        :param request: request to manage.
-        :param connection_handler: connection handler from which the request was sent.
-        :return: an instance of responses.DataGamesToPowerNames
-        :type server: diplomacy.Server
-        :type request: diplomacy.communication.requests.GetDummyWaitingPowers
-    """
-    verify_request(server, request, connection_handler)
-    return responses.DataGamesToPowerNames(
-        data=server.get_dummy_waiting_power_names(request.buffer_size, request.token), request_id=request.request_id)
-
 def on_get_all_possible_orders(server, request, connection_handler):
     """ Manage request GetAllPossibleOrders
+
         :param server: server which receives the request
         :param request: request to manage
         :param connection_handler: connection handler from which the request was sent
@@ -251,6 +245,7 @@ def on_get_all_possible_orders(server, request, connection_handler):
 
 def on_get_available_maps(server, request, connection_handler):
     """ Manage request GetAvailableMaps.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -263,6 +258,7 @@ def on_get_available_maps(server, request, connection_handler):
 
 def on_get_daide_port(server, request, connection_handler):
     """ Manage request GetDaidePort.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -277,21 +273,59 @@ def on_get_daide_port(server, request, connection_handler):
             "Invalid game id %s or game's DAIDE server is not started for that game" % request.game_id)
     return responses.DataPort(data=daide_port, request_id=request.request_id)
 
-def on_get_playable_powers(server, request, connection_handler):
-    """ Manage request GetPlayablePowers.
+def on_get_dummy_waiting_powers(server, request, connection_handler):
+    """ Manage request GetAllDummyPowerNames.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
-        :return: None
+        :return: an instance of responses.DataGamesToPowerNames
         :type server: diplomacy.Server
-        :type request: diplomacy.communication.requests.GetPlayablePowers
+        :type request: diplomacy.communication.requests.GetDummyWaitingPowers
     """
     verify_request(server, request, connection_handler)
-    return responses.DataPowerNames(
-        data=server.get_game(request.game_id).get_dummy_power_names(), request_id=request.request_id)
+    return responses.DataGamesToPowerNames(
+        data=server.get_dummy_waiting_power_names(request.buffer_size, request.token), request_id=request.request_id)
+
+def on_get_games_info(server, request, connection_handler):
+    """ Manage request GetGamesInfo.
+
+        :param server: server which receives the request.
+        :param request: request to manage.
+        :param connection_handler: connection handler from which the request was sent.
+        :return: an instance of responses.DataGames
+        :type server: diplomacy.Server
+        :type request: diplomacy.communication.requests.GetGamesInfo
+    """
+    verify_request(server, request, connection_handler)
+    username = server.users.get_name(request.token)
+    games = []
+    for game_id in request.games:
+        try:
+            server_game = server.load_game(game_id)
+            games.append(responses.DataGameInfo(
+                game_id=server_game.game_id,
+                phase=server_game.current_short_phase,
+                timestamp=server_game.get_latest_timestamp(),
+                timestamp_created=server_game.timestamp_created,
+                map_name=server_game.map_name,
+                observer_level=server_game.get_observer_level(username),
+                controlled_powers=server_game.get_controlled_power_names(username),
+                rules=server_game.rules,
+                status=server_game.status,
+                n_players=server_game.count_controlled_powers(),
+                n_controls=server_game.get_expected_controls_count(),
+                deadline=server_game.deadline,
+                registration_password=bool(server_game.registration_password)
+            ))
+        except exceptions.GameIdException:
+            # Invalid game ID, just pass.
+            pass
+    return responses.DataGames(data=games, request_id=request.request_id)
 
 def on_get_phase_history(server, request, connection_handler):
     """ Manage request GetPhaseHistory.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -304,8 +338,23 @@ def on_get_phase_history(server, request, connection_handler):
     game_phases = level.game.get_phase_history(request.from_phase, request.to_phase, request.game_role)
     return responses.DataGamePhases(data=game_phases, request_id=request.request_id)
 
+def on_get_playable_powers(server, request, connection_handler):
+    """ Manage request GetPlayablePowers.
+
+        :param server: server which receives the request.
+        :param request: request to manage.
+        :param connection_handler: connection handler from which the request was sent.
+        :return: None
+        :type server: diplomacy.Server
+        :type request: diplomacy.communication.requests.GetPlayablePowers
+    """
+    verify_request(server, request, connection_handler)
+    return responses.DataPowerNames(
+        data=server.get_game(request.game_id).get_dummy_power_names(), request_id=request.request_id)
+
 def on_join_game(server, request, connection_handler):
     """ Manage request JoinGame.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -479,6 +528,7 @@ def on_join_powers(server, request, connection_handler):
     """ Manage request JoinPowers.
         Current code does not care about rule POWER_CHOICE. It only
         checks if queried powers can be joined by request sender.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -588,6 +638,7 @@ def on_leave_game(server, request, connection_handler):
     """ Manage request LeaveGame.
         If user is an (omniscient) observer, stop observation.
         Else, stop to control given power name.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -606,6 +657,7 @@ def on_leave_game(server, request, connection_handler):
 
 def on_list_games(server, request, connection_handler):
     """ Manage request ListGames.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -618,7 +670,8 @@ def on_list_games(server, request, connection_handler):
         raise exceptions.MapIdException()
     selected_game_indices = []
     for game_id in server.get_game_indices():
-        if request.game_id and request.game_id not in game_id:
+        if request.game_id and not (game_id.lower() in request.game_id.lower()
+                                    or request.game_id.lower() in game_id.lower()):
             continue
         server_game = server.load_game(game_id)
         if request.for_omniscience and not server.token_is_omniscient(request.token, server_game):
@@ -647,43 +700,9 @@ def on_list_games(server, request, connection_handler):
         ))
     return responses.DataGames(data=selected_game_indices, request_id=request.request_id)
 
-def on_get_games_info(server, request, connection_handler):
-    """ Manage request GetGamesInfo.
-        :param server: server which receives the request.
-        :param request: request to manage.
-        :param connection_handler: connection handler from which the request was sent.
-        :return: an instance of responses.DataGames
-        :type server: diplomacy.Server
-        :type request: diplomacy.communication.requests.GetGamesInfo
-    """
-    verify_request(server, request, connection_handler)
-    username = server.users.get_name(request.token)
-    games = []
-    for game_id in request.games:
-        try:
-            server_game = server.load_game(game_id)
-            games.append(responses.DataGameInfo(
-                game_id=server_game.game_id,
-                phase=server_game.current_short_phase,
-                timestamp=server_game.get_latest_timestamp(),
-                timestamp_created=server_game.timestamp_created,
-                map_name=server_game.map_name,
-                observer_level=server_game.get_observer_level(username),
-                controlled_powers=server_game.get_controlled_power_names(username),
-                rules=server_game.rules,
-                status=server_game.status,
-                n_players=server_game.count_controlled_powers(),
-                n_controls=server_game.get_expected_controls_count(),
-                deadline=server_game.deadline,
-                registration_password=bool(server_game.registration_password)
-            ))
-        except exceptions.GameIdException:
-            # Invalid game ID, just pass.
-            pass
-    return responses.DataGames(data=games, request_id=request.request_id)
-
 def on_logout(server, request, connection_handler):
     """ Manage request Logout.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -695,8 +714,8 @@ def on_logout(server, request, connection_handler):
     server.remove_token(request.token)
 
 def on_process_game(server, request, connection_handler):
-    """ Manage request ProcessGame.
-        Force a game to be processed the sooner.
+    """ Manage request ProcessGame. Force a game to be processed the sooner.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -719,7 +738,7 @@ def on_process_game(server, request, connection_handler):
 @gen.coroutine
 def on_query_schedule(server, request, connection_handler):
     """ Manage request QuerySchedule.
-        Force a game to be processed the sooner.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -740,6 +759,7 @@ def on_query_schedule(server, request, connection_handler):
 
 def on_save_game(server, request, connection_handler):
     """ Manage request SaveGame
+
         :param server: server which receives the request
         :param request: request to manage
         :param connection_handler: connection handler from which the request was sent
@@ -752,6 +772,7 @@ def on_save_game(server, request, connection_handler):
 
 def on_send_game_message(server, request, connection_handler):
     """ Manage request SendGameMessage.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -806,6 +827,7 @@ def on_send_game_message(server, request, connection_handler):
 
 def on_set_dummy_powers(server, request, connection_handler):
     """ Manage request SetDummyPowers.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -834,6 +856,7 @@ def on_set_dummy_powers(server, request, connection_handler):
 
 def on_set_game_state(server, request, connection_handler):
     """ Manage request SetGameState.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -850,6 +873,7 @@ def on_set_game_state(server, request, connection_handler):
 
 def on_set_game_status(server, request, connection_handler):
     """ Manage request SetGameStatus.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -884,6 +908,7 @@ def on_set_game_status(server, request, connection_handler):
 
 def on_set_grade(server, request, connection_handler):
     """ Manage request SetGrade.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -979,11 +1004,11 @@ def on_set_grade(server, request, connection_handler):
             # Check if user omniscient rights was changed.
             user_is_omniscient_after = server.user_is_omniscient(username, server_game)
             if user_is_omniscient_before != user_is_omniscient_after:
-
                 transfer_special_tokens(server_game, server, username, grade_update, user_is_omniscient_after)
 
 def on_set_orders(server, request, connection_handler):
     """ Manage request SetOrders.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1014,6 +1039,7 @@ def on_set_orders(server, request, connection_handler):
 
 def on_set_wait_flag(server, request, connection_handler):
     """ Manage request SetWaitFlag.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1033,6 +1059,7 @@ def on_set_wait_flag(server, request, connection_handler):
 
 def on_sign_in(server, request, connection_handler):
     """ Manage request SignIn.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1061,6 +1088,7 @@ def on_sign_in(server, request, connection_handler):
 
 def on_synchronize(server, request, connection_handler):
     """ Manage request Synchronize.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1128,6 +1156,7 @@ def on_synchronize(server, request, connection_handler):
 
 def on_unknown_token(server, request, connection_handler):
     """ Manage notification request UnknownToken.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1143,6 +1172,7 @@ def on_unknown_token(server, request, connection_handler):
 
 def on_vote(server, request, connection_handler):
     """ Manage request Vote.
+
         :param server: server which receives the request.
         :param request: request to manage.
         :param connection_handler: connection handler from which the request was sent.
@@ -1176,17 +1206,17 @@ MAPPING = {
     requests.CreateGame: on_create_game,
     requests.DeleteAccount: on_delete_account,
     requests.DeleteGame: on_delete_game,
-    requests.GetDummyWaitingPowers: on_get_dummy_waiting_powers,
     requests.GetAllPossibleOrders: on_get_all_possible_orders,
     requests.GetAvailableMaps: on_get_available_maps,
     requests.GetDaidePort: on_get_daide_port,
-    requests.GetPlayablePowers: on_get_playable_powers,
+    requests.GetDummyWaitingPowers: on_get_dummy_waiting_powers,
+    requests.GetGamesInfo: on_get_games_info,
     requests.GetPhaseHistory: on_get_phase_history,
+    requests.GetPlayablePowers: on_get_playable_powers,
     requests.JoinGame: on_join_game,
     requests.JoinPowers: on_join_powers,
     requests.LeaveGame: on_leave_game,
     requests.ListGames: on_list_games,
-    requests.GetGamesInfo: on_get_games_info,
     requests.Logout: on_logout,
     requests.ProcessGame: on_process_game,
     requests.QuerySchedule: on_query_schedule,
@@ -1206,6 +1236,7 @@ MAPPING = {
 
 def handle_request(server, request, connection_handler):
     """ (coroutine) Find request handler function for associated request, run it and return its result.
+
         :param server: a Server object to pass to handler function.
         :param request: a request object to pass to handler function.
             See diplomacy.communication.requests for possible requests.