Doc: Add docstrings to the to/from_dict functions

This commit adds docstrings (and tests!) to the to_dict and from_dict
functions. The docstrings contain examples which can be discovered and
run via doctest. This commit also adds a pytest config file which
enables the doctest option.

Author: Ogaday

howard/__init__.py

@@ -7,6 +7,20 @@
 
 
 def from_dict(d: dict, t: Generic[T]) -> T:
+    """
+    Initialise an instance of the dataclass t using the values in the dict d
+
+    Example:
+
+    >>> @dataclasses.dataclass
+    ... class Person:
+    ...     name: str
+    ...     age: int
+    ...
+    >>> data = {'name': 'Howard', 'age': 24}
+    >>> from_dict(data, Person)
+    Person(name='Howard', age=24)
+    """
     if not isinstance(d, dict):
         raise TypeError("First argument must be of type dict")
     if not dataclasses.is_dataclass(t):
@@ -16,6 +30,20 @@ def from_dict(d: dict, t: Generic[T]) -> T:
 
 
 def to_dict(obj: T, public_only=False) -> dict:
+    """
+    Marshall a dataclass instance into a dict
+
+    Example:
+
+    >>> @dataclasses.dataclass
+    ... class Person:
+    ...     name: str
+    ...     age: int
+    ...
+    >>> instance = Person(name='Howard', age=24)
+    >>> to_dict(instance)
+    {'name': 'Howard', 'age': 24}
+    """
     if not dataclasses.is_dataclass(obj):
         raise TypeError('Argument must be a dataclass')
 

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+addopts = --doctest-modules