From abb42dcd4886705d6ba8af27f68ef605218ac67c Mon Sep 17 00:00:00 2001
From: Philip Paquette <pcpaquette@gmail.com>
Date: Wed, 11 Sep 2019 12:58:45 -0400
Subject: 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>
---
diplomacy/communication/notifications.py | 93 ++++++++++++++++++++++++++------
1 file changed, 77 insertions(+), 16 deletions(-)
(limited to 'diplomacy/communication/notifications.py')
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.
"""
--
cgit v1.2.3