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/utils/jsonable.py | 44 +++++++++++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 17 deletions(-)

(limited to 'diplomacy/utils/jsonable.py')

diff --git a/diplomacy/utils/jsonable.py b/diplomacy/utils/jsonable.py
index 0ce1a21..a103cbb 100644
--- a/diplomacy/utils/jsonable.py
+++ b/diplomacy/utils/jsonable.py
@@ -16,25 +16,30 @@
 # ==============================================================================
 """ Abstract Jsonable class with automatic attributes checking and conversion to/from JSON dict.
     To write a Jsonable sub-class:
+
     - Define a model with expected attribute names and types. Use module `parsing` to describe expected types.
-    - Override initializer __init__(**kwargs):
-      - **first**: initialize each attribute defined in model with value None.
-      - **then** : call parent __init__() method. Attributes will be checked and filled by
-        Jsonable's __init__() method.
-      - If needed, add further initialization code after call to parent __init__() method. At this point,
-        attributes were correctly set based on defined model, and you can now work with them.
+    - Override initializer ``__init__(**kwargs)``:
+
+        - **first**: initialize each attribute defined in model with value None.
+        - **then** : call parent __init__() method. Attributes will be checked and filled by
+          Jsonable's __init__() method.
+        - If needed, add further initialization code after call to parent __init__() method. At this point,
+          attributes were correctly set based on defined model, and you can now work with them.
 
     Example:
-    ```
-    class MyClass(Jsonable):
-        model = {
-            'my_attribute': parsing.Sequence(int),
-        }
-        def __init__(**kwargs):
-            self.my_attribute = None
-            super(MyClass, self).__init__(**kwargs)
-            # my_attribute is now initialized based on model. You can then do any further initialization if needed.
-    ```
+
+    .. code-block:: python
+
+        class MyClass(Jsonable):
+            model = {
+                'my_attribute': parsing.Sequence(int),
+            }
+            def __init__(**kwargs):
+                self.my_attribute = None
+                super(MyClass, self).__init__(**kwargs)
+                # my_attribute is now initialized based on model.
+                # You can then do any further initialization if needed.
+
 """
 import logging
 import ujson as json
@@ -43,7 +48,7 @@ from diplomacy.utils import exceptions, parsing
 
 LOGGER = logging.getLogger(__name__)
 
-class Jsonable():
+class Jsonable:
     """ Abstract class to ease conversion from/to JSON dict. """
     __slots__ = []
     __cached__models__ = {}
@@ -78,12 +83,14 @@ class Jsonable():
 
     def json(self):
         """ Convert this object to a JSON string ready to be sent/saved.
+
             :return: string
         """
         return json.dumps(self.to_dict())
 
     def to_dict(self):
         """ Convert this object to a python dictionary ready for any JSON work.
+
             :return: dict
         """
         model = self.get_model()
@@ -95,6 +102,7 @@ class Jsonable():
             JSON dictionary is passed by class method from_dict() (see below), and is guaranteed to contain
             at least all expected model keys. Some keys may be associated to None if initial JSON dictionary
             did not provide values for them.
+
             :param json_dict: a JSON dictionary to be parsed.
             :type json_dict: dict
         """
@@ -102,6 +110,7 @@ class Jsonable():
     @classmethod
     def from_dict(cls, json_dict):
         """ Convert a JSON dictionary to an instance of this class.
+
             :param json_dict: a JSON dictionary to parse. Dictionary with basic types (int, bool, dict, str, None, etc.)
             :return: an instance from this class or from a derived one from which it's called.
             :rtype: cls
@@ -133,6 +142,7 @@ class Jsonable():
     def get_model(cls):
         """ Return model associated to current class, and cache it for future uses, to avoid
             multiple rendering of model for each class derived from Jsonable. Private method.
+
             :return: dict: model associated to current class.
         """
         if cls not in cls.__cached__models__:
-- 
cgit v1.2.3