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>

2 files changed, 50 insertions, 17 deletions

diff --git a/diplomacy/tests/network/run_real_game.py b/diplomacy/tests/network/run_real_game.py
index a9800b6..e243dec 100644
--- a/diplomacy/tests/network/run_real_game.py
+++ b/diplomacy/tests/network/run_real_game.py
@@ -18,17 +18,27 @@
 """ Run tests from diplomacy.tests.network.test_real_game to test games in a real environment.
     Each test run a game and checks game messages and phases against an expected game data file.
     Current tested gama data files are JSON files located into folder diplomacy/tests/network:
-        1.json
-        2.json
-        3.json
-    Need a local diplomacy server running. You must specify this server port using parameter --port=<server_port>.
-    To run all tests:
+
+    - 1.json
+    - 2.json
+    - 3.json
+
+    Need a local diplomacy server running. You must specify
+    this server port using parameter ``--port=<server_port>``.
+
+    To run all tests: ::
+
         python -m diplomacy.tests.network.run_real_game --port=<server_port>
-    To run a specific test (e.g. 2.json, or 2.json and 1.json):
-        python -m diplomacy.tests.network.run_real_game --cases=20 --port=<server_port>
-        python -m diplomacy.tests.network.run_real_game --cases=15,20 --port=<server_port>
-    For help:
+
+    To run a specific test (e.g. 2.json, or 2.json and 1.json): ::
+
+        python -m diplomacy.tests.network.run_real_game --cases=2 --port=<server_port>
+        python -m diplomacy.tests.network.run_real_game --cases=1,2 --port=<server_port>
+
+    For help: ::
+
         python -m diplomacy.tests.network.run_real_game --help
+
 """
 import argparse
 from tornado import gen
diff --git a/diplomacy/tests/network/test_real_game.py b/diplomacy/tests/network/test_real_game.py
index a960b91..bd63da1 100644
--- a/diplomacy/tests/network/test_real_game.py
+++ b/diplomacy/tests/network/test_real_game.py
@@ -19,6 +19,7 @@
 import logging
 import os
 import random
+from typing import Dict
 
 from tornado import gen
 from tornado.concurrent import Future
@@ -39,12 +40,13 @@ DEFAULT_HOSTNAME = 'localhost'
 
 DEFAULT_PORT = random.randint(9000, 10000)
 
-class ExpectedPhase():
+class ExpectedPhase:
     """ Helper class to manage data from an expected phase. """
     __slots__ = ['name', 'state', 'orders', 'messages']
 
     def __init__(self, json_phase):
         """ Initialize expected phase.
+
             :param json_phase: JSON dict representing a phase. Expected fields: name, state, orders, messages.
         """
         self.name = json_phase['name']
@@ -63,12 +65,13 @@ class ExpectedPhase():
         return [message for message in self.messages
                 if message.sender == power_name or message.recipient in (power_name, GLOBAL)]
 
-class ExpectedMessages():
+class ExpectedMessages:
     """ Expected list of messages sent and received by a power name. """
     __slots__ = ['power_name', 'messages', 'next_messages_to_send']
 
     def __init__(self, power_name, messages):
         """  Initialize the expected messages.
+
             :param power_name: power name which exchanges these messages
             :param messages: messages exchanged
         """
@@ -100,13 +103,14 @@ class ExpectedMessages():
             self.next_messages_to_send.extend(self.messages[:next_message_to_receive])
             del self.messages[:next_message_to_receive]
 
-class ExpectedData():
+class ExpectedData:
     """ Expected data for a power in a game. """
 
     __slots__ = ['messages', 'phases', '__phase_index', 'playing']
 
     def __init__(self, power_name, phases, phase_index):
         """ Initialize expected data for a game power.
+
             :param power_name: name of power for which those data are expected.
             :param phases: list of expected phases.
             :param phase_index: index of current expected phase in given phases.
@@ -130,12 +134,13 @@ class ExpectedData():
             self.messages = ExpectedMessages(
                 self.messages.power_name, self.phases[self.__phase_index].get_power_related_messages(self.power_name))
 
-class CaseData():
+class CaseData:
     """ Helper class to store test data. """
     FILE_FOLDER_NAME = os.path.abspath(os.path.dirname(__file__))
 
     def __init__(self, case_file_name, hostname=DEFAULT_HOSTNAME, port=DEFAULT_PORT):
         """ Initialize game test.
+
             :param case_file_name: File name of JSON file containing expected game data.
                 JSON file must be located in folder FILE_FOLDER_NAME.
             :param hostname: hostname to use to load server.
@@ -157,7 +162,7 @@ class CaseData():
         self.admin_channel = None
         self.admin_game = None
         self.user_games = {}
-        self.future_games_ended = {}  # type: dict{str, Future}
+        self.future_games_ended = {}  # type: Dict[str, Future]
 
         self.hostname = hostname
         self.port = port
@@ -169,6 +174,7 @@ class CaseData():
     @gen.coroutine
     def on_power_phase_update(self, game, notification=None):
         """ User game notification callback for game phase updated.
+
             :param game: game
             :param notification: notification
             :type game: NetworkGame
@@ -187,6 +193,7 @@ class CaseData():
     @gen.coroutine
     def on_power_state_update(self, game, notification):
         """ User game notification callback for game state update.
+
             :param game: game
             :param notification: notification
             :type game: NetworkGame
@@ -198,6 +205,7 @@ class CaseData():
 @gen.coroutine
 def send_messages_if_needed(game, expected_messages):
     """ Take messages to send in top of given messages list and send them.
+
         :param game: a NetworkGame object.
         :param expected_messages: an instance of ExpectedMessages.
         :type game: NetworkGame
@@ -222,6 +230,7 @@ def send_messages_if_needed(game, expected_messages):
 @gen.coroutine
 def send_current_orders(game):
     """ Send expected orders for current phase.
+
         :param game: a Network game object.
         :type game: NetworkGame
     """
@@ -242,6 +251,7 @@ def send_current_orders(game):
 
 def on_message_received(game, notification):
     """ User game notification callback for messages received.
+
         :param game: a NetworkGame object,
         :param notification: a notification received by this game.
         :type game: NetworkGame
@@ -286,6 +296,7 @@ def on_message_received(game, notification):
 
 def on_admin_game_phase_update(admin_game, notification=None):
     """ Admin game notification callback for game phase update.
+
         :param admin_game: admin game
         :param notification: notification
         :type admin_game: NetworkGame
@@ -370,6 +381,7 @@ def on_admin_game_phase_update(admin_game, notification=None):
 
 def on_admin_game_state_update(admin_game, notification):
     """ Admin game notification callback for game state update.
+
         :param admin_game: admin game
         :param notification: notification
         :type admin_game: NetworkGame
@@ -380,6 +392,7 @@ def on_admin_game_state_update(admin_game, notification):
 
 def on_admin_powers_controllers(admin_game, notification):
     """  Admin game notification callback for powers controllers received (unexpected).
+
         :param admin_game: game
         :param notification: notification
         :type admin_game: NetworkGame
@@ -390,6 +403,7 @@ def on_admin_powers_controllers(admin_game, notification):
 
 def on_admin_game_status_update(admin_game, notification):
     """ Admin game notification callback for game status update.
+
         :param admin_game: admin game
         :param notification: notification
         :type admin_game: NetworkGame
@@ -399,9 +413,11 @@ def on_admin_game_status_update(admin_game, notification):
 @gen.coroutine
 def play_phase(game, expected_messages):
     """ Play a phase for a user game:
-        1) Send messages
-        2) wait for messages to receive
-        3) send current orders.
+
+        #. Send messages
+        #. wait for messages to receive
+        #. send current orders.
+
         :param game: user game
         :param expected_messages: expected messages
         :type game: NetworkGame
@@ -418,6 +434,7 @@ def play_phase(game, expected_messages):
 def on_game_status_update(game, notification):
     """ User game notification callback for game status update.
         Used to start the game locally when game started on server.
+
         :param game: game
         :param notification: notification
         :type game: NetworkGame
@@ -434,6 +451,7 @@ def on_game_status_update(game, notification):
 @gen.coroutine
 def verify_current_phase(game):
     """ Check and play current phase.
+
         :param game: a NetWork game object.
         :type game: NetworkGame
     """
@@ -455,6 +473,7 @@ def verify_current_phase(game):
 
 def get_user_game_fn(case_data, power_name):
     """ Return a coroutine procedure that loads and play a user game for given power name.
+
         :param case_data: case data
         :param power_name: str
         :return: a procedure.
@@ -471,6 +490,7 @@ def get_user_game_fn(case_data, power_name):
 def get_future_game_done_fn(power_name):
     """ Return a callback to call when a power game is finished.
         Callback currently just prints a message to tell that power game is terminated.
+
         :param power_name: power name of associated game.
         :return: a callable that receives the future done when game is finished.
     """
@@ -484,6 +504,7 @@ def get_future_game_done_fn(power_name):
 @gen.coroutine
 def load_power_game(case_data, power_name):
     """ Load and play a power game from admin game for given power name.
+
         :type case_data: CaseData
     """
     print('Loading game for power', power_name)
@@ -519,6 +540,7 @@ def load_power_game(case_data, power_name):
 def main(case_data):
     """ Test real game environment with one game and all power controlled (no dummy powers).
         This method may be called form a non-test code to run a real game case.
+
         :param case_data: test data
         :type case_data: CaseData
     """
@@ -567,6 +589,7 @@ def run(case_data, **server_kwargs):
         Load a server (with optional given server kwargs),
         call function main(case_data) as client code
         and wait for main function to terminate.
+
         :type case_data: CaseData
     """