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, 77 insertions, 16 deletions

diff --git a/diplomacy/communication/notifications.py b/diplomacy/communication/notifications.py
index c88d526..1751182 100644
--- a/diplomacy/communication/notifications.py
+++ b/diplomacy/communication/notifications.py
@@ -73,7 +73,13 @@ class AccountDeleted(_ChannelNotification):
     __slots__ = []
 
 class OmniscientUpdated(_GameNotification):
-    """ Notification about a grade updated. Sent at channel level. """
+    """ Notification about a grade updated. Sent at channel level.
+
+        Properties:
+
+            - **grade_update**: :class:`str` One of 'promote' or 'demote'.
+            - **game**: :class:`parsing.JsonableClassType(Game)` a :class:`diplomacy.engine.game.Game` object.
+    """
     __slots__ = ['grade_update', 'game']
     params = {
         strings.GRADE_UPDATE: parsing.EnumerationType(strings.ALL_GRADE_UPDATES),
@@ -98,10 +104,12 @@ class ClearedUnits(_GameNotification):
     __slots__ = []
 
 class VoteCountUpdated(_GameNotification):
-    """ Notification about new count of draw votes for a game (for observers)
+    """ Notification about new count of draw votes for a game (for observers).
+
         Properties:
-        - count_voted: number of powers that have voted.
-        - count_expected: number of powers to be expected to vote.
+
+            - **count_voted**: :class:`int` number of powers that have voted.
+            - **count_expected**: :class:`int` number of powers to be expected to vote.
     """
     __slots__ = ['count_voted', 'count_expected']
     params = {
@@ -115,8 +123,12 @@ class VoteCountUpdated(_GameNotification):
         super(VoteCountUpdated, self).__init__(**kwargs)
 
 class VoteUpdated(_GameNotification):
-    """ Notification about votes updated for a game (for omniscient observers). Properties:
-        - vote: dictionary mapping a power name to a Vote object representing power vote.
+    """ Notification about votes updated for a game (for omniscient observers).
+
+        Properties:
+
+            - **vote**: :class:`Dict` mapping a power name to a Vote (:class:`str`) object representing power vote.
+              Possible votes are: yes, no, neutral.
     """
     __slots__ = ['vote']
     params = {
@@ -128,8 +140,11 @@ class VoteUpdated(_GameNotification):
         super(VoteUpdated, self).__init__(**kwargs)
 
 class PowerVoteUpdated(VoteCountUpdated):
-    """ Notification about a new vote for a specific game power (for player games). Properties:
-        - vote: vote object representing associated power vote.
+    """ Notification about a new vote for a specific game power (for player games).
+
+        Properties:
+
+            - **vote**: :class:`str` vote object representing associated power vote. Can be yes, no, neutral.
     """
     __slots__ = ['vote']
     params = parsing.extend_model(VoteCountUpdated.params, {
@@ -141,7 +156,13 @@ class PowerVoteUpdated(VoteCountUpdated):
         super(PowerVoteUpdated, self).__init__(**kwargs)
 
 class PowersControllers(_GameNotification):
-    """ Notification about current controller for each power in a game. """
+    """ Notification about current controller for each power in a game.
+
+        Properties:
+
+            - **powers**: A :class:`Dict` that maps a power_name to a controller_name :class:`str`.
+            - **timestamps**: A :class:`Dict` that maps a power_name to timestamp where the controller took over.
+    """
     __slots__ = ['powers', 'timestamps']
     params = {
         # {power_name => controller_name}
@@ -160,7 +181,13 @@ class GameDeleted(_GameNotification):
     __slots__ = []
 
 class GameProcessed(_GameNotification):
-    """ Notification about a game phase update. Sent after game had processed a phase. """
+    """ Notification about a game phase update. Sent after game has processed a phase.
+
+        Properties:
+
+            - **previous_phase_data**: :class:`diplomacy.utils.game_phase_data.GamePhaseData` of the previous phase
+            - **current_phase_data**: :class:`diplomacy.utils.game_phase_data.GamePhaseData` of the current phase
+    """
     __slots__ = ['previous_phase_data', 'current_phase_data']
     params = {
         strings.PREVIOUS_PHASE_DATA: parsing.JsonableClassType(GamePhaseData),
@@ -173,7 +200,13 @@ class GameProcessed(_GameNotification):
         super(GameProcessed, self).__init__(**kwargs)
 
 class GamePhaseUpdate(_GameNotification):
-    """ Notification about a game phase update. """
+    """ Notification about a game phase update.
+
+        Properties:
+
+            - **phase_data**: :class:`diplomacy.utils.game_phase_data.GamePhaseData` of the updated phase
+            - **phase_data_type**: :class:`str`. One of 'state_history', 'state', 'phase'
+    """
     __slots__ = ['phase_data', 'phase_data_type']
     params = {
         strings.PHASE_DATA: parsing.JsonableClassType(GamePhaseData),
@@ -186,7 +219,12 @@ class GamePhaseUpdate(_GameNotification):
         super(GamePhaseUpdate, self).__init__(**kwargs)
 
 class GameStatusUpdate(_GameNotification):
-    """ Notification about a game status update. """
+    """ Notification about a game status update.
+
+        Properties:
+
+            -**status**: :class:`str`. One of 'forming', 'active', 'paused', 'completed', 'canceled'
+    """
     __slots__ = ['status']
     params = {
         strings.STATUS: parsing.EnumerationType(strings.ALL_GAME_STATUSES),
@@ -197,7 +235,12 @@ class GameStatusUpdate(_GameNotification):
         super(GameStatusUpdate, self).__init__(**kwargs)
 
 class GameMessageReceived(_GameNotification):
-    """ Notification about a game message received. """
+    """ Notification about a game message received.
+
+        Properties:
+
+            - **message**: :class:`diplomacy.engine.message.Message` received.
+    """
     __slots__ = ['message']
     params = {
         strings.MESSAGE: parsing.JsonableClassType(Message),
@@ -208,7 +251,12 @@ class GameMessageReceived(_GameNotification):
         super(GameMessageReceived, self).__init__(**kwargs)
 
 class PowerOrdersUpdate(_GameNotification):
-    """ Notification about a power order update. """
+    """ Notification about a power order update.
+
+        Properties:
+
+            - **orders**: List of updated orders (i.e. :class:`str`)
+    """
     __slots__ = ['orders']
     params = {
         strings.ORDERS: parsing.OptionalValueType(parsing.SequenceType(str)),
@@ -219,7 +267,12 @@ class PowerOrdersUpdate(_GameNotification):
         super(PowerOrdersUpdate, self).__init__(**kwargs)
 
 class PowerOrdersFlag(_GameNotification):
-    """ Notification about a power order flag update. """
+    """ Notification about a power order flag update.
+
+        Properties:
+
+            - **order_is_set**: :class:`int`. O = ORDER_NOT_SET, 1 = ORDER_SET_EMPTY, 2 = ORDER_SET.
+    """
     __slots__ = ['order_is_set']
     params = {
         strings.ORDER_IS_SET: parsing.EnumerationType(OrderSettings.ALL_SETTINGS),
@@ -230,7 +283,14 @@ class PowerOrdersFlag(_GameNotification):
         super(PowerOrdersFlag, self).__init__(**kwargs)
 
 class PowerWaitFlag(_GameNotification):
-    """ Notification about a power wait flag update. """
+    """ Notification about a power wait flag update.
+
+        Properties:
+
+            - **wait**: :class:`bool` that indicates to wait until the deadline is reached before proceeding. Otherwise
+              if all powers are not waiting, the game is processed as soon as all non-eliminated powers have submitted
+              their orders.
+    """
     __slots__ = ['wait']
     params = {
         strings.WAIT: bool,
@@ -242,6 +302,7 @@ class PowerWaitFlag(_GameNotification):
 
 def parse_dict(json_notification):
     """ Parse a JSON expected to represent a notification. Raise an exception if parsing failed.
+
         :param json_notification: JSON dictionary.
         :return: a notification class instance.
     """