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/daide/responses.py | 206 +++++++++++++++++++++++++++++++++----------
1 file changed, 157 insertions(+), 49 deletions(-)
(limited to 'diplomacy/daide/responses.py')
diff --git a/diplomacy/daide/responses.py b/diplomacy/daide/responses.py
index cd7a5b4..fe77e1a 100644
--- a/diplomacy/daide/responses.py
+++ b/diplomacy/daide/responses.py
@@ -41,7 +41,9 @@ class DaideResponse(_AbstractResponse):
class MapNameResponse(DaideResponse):
""" Represents a MAP DAIDE response. Sends the name of the current map to the client.
- Syntax:
+
+ Syntax: ::
+
MAP ('name')
"""
def __init__(self, map_name, **kwargs):
@@ -54,11 +56,17 @@ class MapNameResponse(DaideResponse):
class MapDefinitionResponse(DaideResponse):
""" Represents a MDF DAIDE response. Sends configuration of a map to a client
- Syntax:
+
+ Syntax: ::
+
MDF (powers) (provinces) (adjacencies)
- powers syntax:
+
+ powers syntax: ::
+
power power ...
- power syntax:
+
+ power syntax: ::
+
AUS # Austria
ENG # England
FRA # France
@@ -66,11 +74,17 @@ class MapDefinitionResponse(DaideResponse):
ITA # Italy
RUS # Russia
TUR # Turkey
- provinces syntax:
+
+ provinces syntax: ::
+
(supply_centres) (non_supply_centres)
- supply_centres syntax:
+
+ supply_centres syntax: ::
+
(power centre centre ...) (power centre centre ...) ...
- supply_centres power syntax:
+
+ supply_centres power syntax: ::
+
(power power ...) # This is currently not supported
AUS # Austria
ENG # England
@@ -80,22 +94,33 @@ class MapDefinitionResponse(DaideResponse):
RUS # Russia
TUR # Turkey
UNO # Unknown power
- non_supply_centres syntax:
+
+ non_supply_centres syntax: ::
+
province province ... # List of provinces
- adjacencies syntax:
+
+ adjacencies syntax: ::
+
(prov_adjacencies) (prov_adjacencies) ...
- prov_adjacencies syntax:
+
+ prov_adjacencies syntax: ::
+
province (unit_type adjacent_prov adjacent_prov ...) (unit_type adjacent_prov adjacent_prov ...) ...
- unit_type syntax:
+
+ unit_type syntax: ::
+
AMY # List of provinces an army can move to
FLT # List of provinces a fleet can move to
(FLT coast) # List of provinces a fleet can move to from the given coast
- adjacent_prov syntax:
+
+ adjacent_prov syntax: ::
+
province # A province which can be moved to
(province coast) # A coast of a province that can be moved to
"""
def __init__(self, map_name, **kwargs):
""" Builds the response
+
:param map_name: The name of the map
"""
super(MapDefinitionResponse, self).__init__(**kwargs)
@@ -116,11 +141,17 @@ class MapDefinitionResponse(DaideResponse):
@staticmethod
def _build_powers_clause(game_map):
""" Build the powers clause
- Syntax:
+
+ Syntax: ::
+
(powers)
- powers syntax:
+
+ powers syntax: ::
+
power power ...
- power syntax:
+
+ power syntax: ::
+
AUS # Austria
ENG # England
FRA # France
@@ -140,13 +171,21 @@ class MapDefinitionResponse(DaideResponse):
@staticmethod
def _build_provinces_clause(game_map):
""" Build the provinces clause
- Syntax:
+
+ Syntax: ::
+
(provinces)
- provinces syntax:
+
+ provinces syntax: ::
+
(supply_centres) (non_supply_centres)
- supply_centres syntax:
+
+ supply_centres syntax: ::
+
(power centre centre ...) (power centre centre ...) ...
- supply_centres power syntax:
+
+ supply_centres power syntax: ::
+
(power power ...) # This is currently not supported
AUS # Austria
ENG # England
@@ -156,7 +195,9 @@ class MapDefinitionResponse(DaideResponse):
RUS # Russia
TUR # Turkey
UNO # Unknown power
- non_supply_centres syntax:
+
+ non_supply_centres syntax: ::
+
province province ... # List of provinces
"""
unowned_scs = game_map.scs[:]
@@ -215,17 +256,27 @@ class MapDefinitionResponse(DaideResponse):
@staticmethod
def _build_adjacencies_clause(game_map):
""" Build the adjacencies clause
- Syntax:
+
+ Syntax: ::
+
(adjacencies)
- adjacencies syntax:
+
+ adjacencies syntax: ::
+
(prov_adjacencies) (prov_adjacencies) ...
- prov_adjacencies syntax:
+
+ prov_adjacencies syntax: ::
+
province (unit_type adjacent_prov adjacent_prov ...) (unit_type adjacent_prov adjacent_prov ...) ...
- unit_type syntax:
+
+ unit_type syntax: ::
+
AMY # List of provinces an army can move to
FLT # List of provinces a fleet can move to
(FLT coast) # List of provinces a fleet can move to from the given coast
- adjacent_prov syntax:
+
+ adjacent_prov syntax: ::
+
province # A province which can be moved to
(province coast) # A coast of a province that can be moved to
"""
@@ -309,17 +360,24 @@ class MapDefinitionResponse(DaideResponse):
class HelloResponse(DaideResponse):
""" Represents a HLO DAIDE response. Sends the power to be played by the client with the passcode to rejoin the
game and the details of the game.
- Syntax:
+
+ Syntax: ::
+
HLO (power) (passcode) (variant) (variant) ...
- Variant syntax:
+
+ Variant syntax: ::
+
LVL n # Level of the syntax accepted
MTL seconds # Movement time limit
RTL seconds # Retreat time limit
BTL seconds # Build time limit
DSD # Disables the time limit when a client disconects
AOA # Any orders accepted
+
LVL 10:
- Variant syntax:
+
+ Variant syntax: ::
+
PDA # Accept partial draws
NPR # No press during retreat phases
NPB # No press during build phases
@@ -327,6 +385,7 @@ class HelloResponse(DaideResponse):
"""
def __init__(self, power_name, passcode, level, deadline, rules, **kwargs):
""" Builds the response
+
:param power_name: The name of the power being played.
:param passcode: Integer. A passcode to rejoin the game.
:param level: Integer. The daide syntax level of the game
@@ -356,11 +415,14 @@ class HelloResponse(DaideResponse):
class SupplyCenterResponse(DaideResponse):
""" Represents a SCO DAIDE response. Sends the current supply centre ownership.
- Syntax:
+
+ Syntax: ::
+
SCO (power centre centre ...) (power centre centre ...) ...
"""
def __init__(self, powers_centers, map_name, **kwargs):
""" Builds the response
+
:param powers_centers: A dict of {power_name: centers} objects
:param map_name: The name of the map
"""
@@ -397,15 +459,20 @@ class SupplyCenterResponse(DaideResponse):
class CurrentPositionResponse(DaideResponse):
""" Represents a NOW DAIDE response. Sends the current turn, and the current unit positions.
- Syntax:
+
+ Syntax: ::
+
NOW (turn) (unit) (unit) ...
- Unit syntax:
+
+ Unit syntax: ::
+
power unit_type province
power unit_type province MRT (province province ...)
"""
def __init__(self, phase_name, powers_units, powers_retreats, **kwargs):
""" Builds the response
+
:param phase_name: The name of the current phase (e.g. 'S1901M')
:param powers: A list of `diplomacy.engine.power.Power` objects
"""
@@ -436,9 +503,13 @@ class CurrentPositionResponse(DaideResponse):
class ThanksResponse(DaideResponse):
""" Represents a THX DAIDE response. Sends the result of an order after submission.
- Syntax:
+
+ Syntax: ::
+
THX (order) (note)
- Note syntax:
+
+ Note syntax: ::
+
MBV # Order is OK.
FAR # Not adjacent.
NSP # No such province
@@ -461,6 +532,7 @@ class ThanksResponse(DaideResponse):
"""
def __init__(self, order_bytes, results, **kwargs):
""" Builds the response
+
:param order_bytes: The bytes received for the order
:param results: An array containing the error codes.
"""
@@ -476,13 +548,16 @@ class ThanksResponse(DaideResponse):
class MissingOrdersResponse(DaideResponse):
""" Represents a MIS DAIDE response. Sends the list of unit for which an order is missing or indication about
required disbands or builds.
- Syntax:
+
+ Syntax: ::
+
MIS (unit) (unit) ...
MIS (unit MRT (province province ...)) (unit MRT (province province ...)) ...
MIS (number)
"""
def __init__(self, phase_name, power, **kwargs):
""" Builds the response
+
:param phase_name: The name of the current phase (e.g. 'S1901M')
:param power: The power to check for missing orders
:type power: diplomacy.engine.power.Power
@@ -558,10 +633,14 @@ class MissingOrdersResponse(DaideResponse):
class OrderResultResponse(DaideResponse):
""" Represents a ORD DAIDE response. Sends the result of an order after the turn has been processed.
- Syntax:
+
+ Syntax: ::
+
ORD (turn) (order) (result)
ORD (turn) (order) (result RET)
- Result syntax:
+
+ Result syntax: ::
+
SUC # Order succeeded (can apply to any order).
BNC # Move bounced (only for MTO, CTO or RTO orders).
CUT # Support cut (only for SUP orders).
@@ -571,6 +650,7 @@ class OrderResultResponse(DaideResponse):
"""
def __init__(self, phase_name, order_bytes, results, **kwargs):
""" Builds the response
+
:param phase_name: The name of the current phase (e.g. 'S1901M')
:param order_bytes: The bytes received for the order
:param results: An array containing the error codes.
@@ -587,11 +667,14 @@ class OrderResultResponse(DaideResponse):
class TimeToDeadlineResponse(DaideResponse):
""" Represents a TME DAIDE response. Sends the time to the next deadline.
- Syntax:
+
+ Syntax: ::
+
TME (seconds)
"""
def __init__(self, seconds, **kwargs):
""" Builds the response
+
:param seconds: Integer. The number of seconds before deadline
"""
super(TimeToDeadlineResponse, self).__init__(**kwargs)
@@ -599,7 +682,9 @@ class TimeToDeadlineResponse(DaideResponse):
class AcceptResponse(DaideResponse):
""" Represents a YES DAIDE request.
- Syntax:
+
+ Syntax: ::
+
YES (TME (seconds)) # Accepts to set the time when a
TME message will be sent
YES (NOT (TME)) # Accepts to cancel all requested time messages
@@ -610,7 +695,9 @@ class AcceptResponse(DaideResponse):
processing the orders for the turn
YES (DRW) # Accepts to draw
YES (NOT (DRW)) # Accepts to cancel a draw request
- LVL 10:
+
+ LVL 10: ::
+
YES (DRW (power power ...)) # Accepts a partial draw
YES (NOT (DRW (power power ...))) # Accepts to cancel a partial draw request
(? not mentinned in the DAIDE doc)
@@ -619,6 +706,7 @@ class AcceptResponse(DaideResponse):
"""
def __init__(self, request_bytes, **kwargs):
""" Builds the response
+
:param request_bytes: The bytes received for the request
"""
super(AcceptResponse, self).__init__(**kwargs)
@@ -626,7 +714,9 @@ class AcceptResponse(DaideResponse):
class RejectResponse(DaideResponse):
""" Represents a REJ DAIDE request.
- Syntax:
+
+ Syntax: ::
+
REJ (NME ('name') ('version')) # Rejects a client in the game
REJ (IAM (power) (passcode)) # Rejects a client to rejoin the game
REJ (HLO) # Rejects to send the HLO message
@@ -647,7 +737,9 @@ class RejectResponse(DaideResponse):
REJ (ADM ('name') ('message') # Rejects the admin message
REJ (DRW) # Rejects to draw
REJ (NOT (DRW)) # Rejects to cancel a draw request
- LVL 10:
+
+ LVL 10: ::
+
REJ (DRW (power power ...)) # Rejects to partially draw
REJ (NOT (DRW (power power ...))) # Rejects to cancel a partial draw request
REJ (SND (power power ...) (press_message)) # Rejects a press message
@@ -655,6 +747,7 @@ class RejectResponse(DaideResponse):
"""
def __init__(self, request_bytes, **kwargs):
""" Builds the response
+
:param request_bytes: The bytes received for the request
"""
super(RejectResponse, self).__init__(**kwargs)
@@ -662,7 +755,9 @@ class RejectResponse(DaideResponse):
class NotResponse(DaideResponse):
""" Represents a NOT DAIDE response.
- Syntax:
+
+ Syntax: ::
+
NOT (CCD (power))
"""
def __init__(self, response_bytes, **kwargs):
@@ -674,11 +769,14 @@ class NotResponse(DaideResponse):
class PowerInCivilDisorderResponse(DaideResponse):
""" Represents a CCD DAIDE response. Sends the name of the power in civil disorder.
- Syntax:
+
+ Syntax: ::
+
CCD (power)
"""
def __init__(self, power_name, **kwargs):
""" Builds the response
+
:param power_name: The name of the power being played.
"""
super(PowerInCivilDisorderResponse, self).__init__(**kwargs)
@@ -687,11 +785,14 @@ class PowerInCivilDisorderResponse(DaideResponse):
class PowerIsEliminatedResponse(DaideResponse):
""" Represents a OUT DAIDE response. Sends the name of the power eliminated.
- Syntax:
+
+ Syntax: ::
+
OUT (power)
"""
def __init__(self, power_name, **kwargs):
""" Builds the response
+
:param power_name: The name of the power being played.
"""
super(PowerIsEliminatedResponse, self).__init__(**kwargs)
@@ -700,11 +801,14 @@ class PowerIsEliminatedResponse(DaideResponse):
class ParenthesisErrorResponse(DaideResponse):
""" Represents a PRN DAIDE response.
- Syntax:
+
+ Syntax: ::
+
PRN (message)
"""
def __init__(self, request_bytes, **kwargs):
""" Builds the response
+
:param request_bytes: The bytes received for the request
"""
super(ParenthesisErrorResponse, self).__init__(**kwargs)
@@ -712,11 +816,14 @@ class ParenthesisErrorResponse(DaideResponse):
class SyntaxErrorResponse(DaideResponse):
""" Represents a HUH DAIDE response.
- Syntax:
+
+ Syntax: ::
+
HUH (message)
"""
def __init__(self, request_bytes, error_index, **kwargs):
""" Builds the response
+
:param request_bytes: The bytes received for the request
:param error_index: The index of the faulty token
"""
@@ -726,12 +833,13 @@ class SyntaxErrorResponse(DaideResponse):
class TurnOffResponse(DaideResponse):
""" Represents an OFF DAIDE response. Requests a client to exit
- Syntax:
+
+ Syntax: ::
+
OFF
"""
def __init__(self, **kwargs):
- """ Builds the response
- """
+ """ Builds the response """
super(TurnOffResponse, self).__init__(**kwargs)
self._bytes = bytes(tokens.OFF)
--
cgit v1.2.3