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, 157 insertions, 49 deletions

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)