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, 67 insertions, 24 deletions

diff --git a/diplomacy/daide/notifications.py b/diplomacy/daide/notifications.py
index e9f6366..625c46a 100644
--- a/diplomacy/daide/notifications.py
+++ b/diplomacy/daide/notifications.py
@@ -22,7 +22,7 @@ from diplomacy.daide import tokens
 from diplomacy.daide.tokens import Token
 from diplomacy.daide.utils import bytes_to_str, str_to_bytes
 
-class DaideNotification():
+class DaideNotification:
     """ Represents a DAIDE response. """
     def __init__(self, **kwargs):
         """ Constructor """
@@ -48,7 +48,9 @@ class DaideNotification():
 
 class MapNameNotification(DaideNotification):
     """ 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):
@@ -60,19 +62,26 @@ class MapNameNotification(DaideNotification):
                       + bytes(parse_string(String, map_name))
 
 class HelloNotification(DaideNotification):
-    """ 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:
+    """ 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: ::
+
             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
@@ -80,6 +89,7 @@ class HelloNotification(DaideNotification):
     """
     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
@@ -109,11 +119,14 @@ class HelloNotification(DaideNotification):
 
 class SupplyCenterNotification(DaideNotification):
     """ Represents a SCO DAIDE notification. 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 notification
+
             :param powers_centers: A dict of {power_name: centers} objects
             :param map_name: The name of the map
         """
@@ -150,14 +163,19 @@ class SupplyCenterNotification(DaideNotification):
 
 class CurrentPositionNotification(DaideNotification):
     """ Represents a NOW DAIDE notification. 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 notification
+
             :param phase_name: The name of the current phase (e.g. 'S1901M')
             :param powers: A list of `diplomacy.engine.power.Power` objects
         """
@@ -187,9 +205,11 @@ class CurrentPositionNotification(DaideNotification):
         self._bytes = bytes(tokens.NOW) + bytes(turn_clause) + b''.join(units_bytes_buffer)
 
 class MissingOrdersNotification(DaideNotification):
-    """ Represents a MIS DAIDE response. Sends the list of unit for which an order is missing or indication about
-        required disbands or builds.
-        Syntax:
+    """ Represents a MIS DAIDE response. Sends the list of unit for which an order is missing
+        or indication about required disbands or builds.
+
+        Syntax: ::
+
             MIS (unit) (unit) ...
             MIS (unit MRT (province province ...)) (unit MRT (province province ...)) ...
             MIS (number)
@@ -268,10 +288,14 @@ class MissingOrdersNotification(DaideNotification):
 
 class OrderResultNotification(DaideNotification):
     """ 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).
@@ -281,6 +305,7 @@ class OrderResultNotification(DaideNotification):
     """
     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.
@@ -299,7 +324,9 @@ class OrderResultNotification(DaideNotification):
 
 class TimeToDeadlineNotification(DaideNotification):
     """ Represents a TME DAIDE response. Sends the time to the next deadline.
-        Syntax:
+
+        Syntax: ::
+
             TME (seconds)
     """
     def __init__(self, seconds, **kwargs):
@@ -311,7 +338,9 @@ class TimeToDeadlineNotification(DaideNotification):
 
 class PowerInCivilDisorderNotification(DaideNotification):
     """ Represents a CCD DAIDE response. Sends the name of the power in civil disorder.
-        Syntax:
+
+        Syntax: ::
+
             CCD (power)
     """
     def __init__(self, power_name, **kwargs):
@@ -324,7 +353,9 @@ class PowerInCivilDisorderNotification(DaideNotification):
 
 class PowerIsEliminatedNotification(DaideNotification):
     """ Represents a OUT DAIDE response. Sends the name of the power eliminated.
-        Syntax:
+
+        Syntax: ::
+
             OUT (power)
     """
     def __init__(self, power_name, **kwargs):
@@ -337,7 +368,9 @@ class PowerIsEliminatedNotification(DaideNotification):
 
 class DrawNotification(DaideNotification):
     """ Represents a DRW DAIDE response. Indicates that the game has ended due to a draw
-        Syntax:
+
+        Syntax: ::
+
             DRW
     """
     def __init__(self, **kwargs):
@@ -348,7 +381,9 @@ class DrawNotification(DaideNotification):
 
 class MessageFromNotification(DaideNotification):
     """ Represents a FRM DAIDE response. Indicates that the game has ended due to a draw
-        Syntax:
+
+        Syntax: ::
+
             FRM (power) (power power ...) (press_message)
             FRM (power) (power power ...) (reply)
     """
@@ -367,7 +402,9 @@ class MessageFromNotification(DaideNotification):
 
 class SoloNotification(DaideNotification):
     """ Represents a SLO DAIDE response. Indicates that the game has ended due to a solo by the specified power
-        Syntax:
+
+        Syntax: ::
+
             SLO (power)
     """
     def __init__(self, power_name, **kwargs):
@@ -380,9 +417,13 @@ class SoloNotification(DaideNotification):
 
 class SummaryNotification(DaideNotification):
     """ Represents a SMR DAIDE response. Sends the summary for each power at the end of the game
-        Syntax:
+
+        Syntax: ::
+
             SMR (turn) (power_summary) ...
-        power_summary syntax:
+
+        power_summary syntax: ::
+
             power ('name') ('version') number_of_centres
             power ('name') ('version') number_of_centres year_of_elimination
     """
@@ -425,7 +466,9 @@ class SummaryNotification(DaideNotification):
 
 class TurnOffNotification(DaideNotification):
     """ Represents an OFF DAIDE response. Requests a client to exit
-        Syntax:
+
+        Syntax: ::
+
             OFF
     """
     def __init__(self, **kwargs):