Merge pull request #12 from RookieGameDevs/initial_documentation

Refactoring of documentation

README.rst

@@ -2,6 +2,10 @@
 Revived
 =======
 
+.. image:: https://readthedocs.org/projects/revived/badge/?version=latest
+   :target: http://revived.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
 ---------------------------------------------------------------------
 A predictable state container for python *heavily* inspired by Redux_
 ---------------------------------------------------------------------
@@ -14,10 +18,17 @@ do pretty much the same job in the most pythonic way possible.
 
 Contents
 --------
+* Documentation_
 * Installation_
 * Examples_
 * Contribute_
-* Documentation_
+
+Documentation
+-------------
+
+Currently the documentation is not buliding into ReadTheDocs (see
+`issue #11 <https://github.com/RookieGameDevs/revived/issues/11>`_). You can
+build the documentation locally. Check out Contribute_ section.
 
 Installation
 ------------
@@ -71,11 +82,6 @@ Contribute
 #. Create a pull request.
 #. Profit :)
 
-Documentation
--------------
-
-More detailed documentation is **coming soon**.
-
 .. _Redux: http://redux.js.org/
 .. _`Redux API`: Redux_
 .. _virtualenv: https://virtualenv.pypa.io/en/stable/

docs/api/action.rst

@@ -1,6 +1,5 @@
-=======================================
-``revived.action`` module documentation
-=======================================
+Action (``revived.action``) module documentation
+================================================
 
 .. automodule:: revived.action
    :members:

docs/api/reducer.rst

@@ -1,6 +1,5 @@
-========================================
-``revived.reducer`` module documentation
-========================================
+Reducer (``revived.reducer``) module documentation
+==================================================
 
 .. automodule:: revived.reducer
    :members:

docs/api/store.rst

@@ -1,6 +1,5 @@
-======================================
-``revived.store`` module documentation
-======================================
+Store (``revived.store``) module documentation
+==============================================
 
 .. automodule:: revived.store
    :members:

docs/conf.py

@@ -33,8 +33,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
-    'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx_autodoc_typehints'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

requirements.txt

@@ -1,5 +1,6 @@
 mypy
 pytest
-sphinx-autobuild
 Sphinx
-sphinx_rtd_theme
+sphinx_rtd_theme
+sphinx-autobuild
+sphinx-autodoc-typehints

revived/action.py

@@ -1,8 +1,59 @@
-"""Action module.
-
+"""
 This module implements helper functions and classes that can be used to define
-actions and action creators, in the same fashion of redux ones, but using
-decorators instead of anonymous functions.
+``actions`` and ``action creators``, in the same fashion of redux ones, but
+using decorators instead of anonymous functions.
+
+Actions and action creators
+===========================
+
+Actions are payloads of information that send data from your application to your
+``store``. They are the only source of information for the ``store``. You send
+them to the store using :any:`revived.store.Store.dispatch`.
+
+Actions are instances of :any:`revived.action.Action`. They have a type
+property. Types should be defined in an enum inheriting
+:any:`revived.action.ActionType`. Once your app is large enough, you may want to
+move them into a separate module.
+
+Action creators are exactly that: functions that create ``actions``. It's easy
+to conflate the terms ``action`` and ``action creator``, so do your best to use
+the *proper term*.
+
+Define action types
+===================
+
+While you are free to define the action type enum as he prefers, it is
+**strongly suggested** to write them down in this way:
+
+.. code:: python
+
+    from revived.actions import ActionType as BaseActionType
+
+    # custom action types enum
+    class ActionType(BaseActionType):
+        AN_ACTION_TYPE = 'an_action_type'
+
+
+Define action creators
+======================
+
+While it is possible to explicitly build :any:`revived.action.Action` instances
+directly, it is **strongly suggested** to create ``actions`` using ``action
+creators``.
+
+Assuming you are in the same module of the ``action types`` defined previously,
+you can define ``action creators`` in this way:
+
+.. code:: python
+
+    # define the action creator that takes two arguments and returns a
+    # dictionary with those arguments in an arbitrary way.
+    @action(ActionTypes.AN_ACTION_TYPE)
+    def an_action_type_with_parameters(param1, param2):
+        return {'1': param1, '2': param2}
+
+    # create the action object
+    action_obj = an_action_type_with_parameters(1, 2)
 """
 from enum import Enum
 from enum import unique
@@ -21,44 +72,44 @@ class ActionType(str, Enum):
     for each module. Usually there would be no need for such a feature-less
     class, but it is pretty handy while using type hints.
     """
-    pass
+    # FIXME: this method is added to avoid sphinx_autodoc_typehints errors:
+    # see https://github.com/agronholm/sphinx-autodoc-typehints/issues/12
+    def __init__(*args, **kwargs):
+        pass
 
 
 class Action(dict):
     """Structure that stores all the required data for an action.
 
     Redux actions are plain objects - ie: python dicts - but having a specific
     class here helps for type hinting. The rationale behind this is that we
-    store the type as *metadata* instead of part of the action data itself.
-    """
+    store the type as ``metadata`` instead of part of the action data itself.
 
-    def __init__(self, action_type: ActionType, data: Optional[Dict[str, Any]]=None) -> None:
-        """Constructor.
+    While ``action_type`` is going to be stored as ``metadata``, the
+    :any:`revived.action.Action` instance itself is going to behave exactly as a
+    dict, with all the action data inside.
 
-        Builds an action using the specified action type and optional data.
-        While action_type is going to be stored as *metadata*, the Action object
-        itself is going to behave exactly as a dict, with all the action data
-        inside.
+    :param action_type: The type of the action.
+    :param data: An optional dict containing data. No restriction on depth
+        and members type, as long as the keys are strings.
+    """
 
-        :param action_type: The type of the action.
-        :param data: An optional dict containing data. No restriction on depth
-            and members type, as long as the keys are strings.
-        """
+    def __init__(self, action_type: ActionType, data: Optional[Dict[str, Any]]=None) -> None:
         super().__init__(**(data or {}))
         self.type = action_type
 
 
 def action(action_type: ActionType) -> Callable[[Callable], Callable]:
-    """Decorator function to use as an *action creator* factory.
+    """Decorator function to use as an ``action creator`` factory.
 
     This helper function is used to create action creators. The idea behind this
-    is that we just want to define the relevant data as a dict, instead of
-    complex objects. This decorator will take care of simple-dict-returing
-    functions preparing the proper Action object that is needed by the revived
-    API.
+    is that we just want to define the relevant data as a ``dict``, instead of
+    complex objects. This decorator will take care of simple-dict-returning
+    functions preparing the proper :any:`revived.action.Action` instance that
+    is needed by the revived API.
 
     :param action_type: The type of the action.
-    :returns: The action creator.
+    :returns: The ``action creator``.
     """
     def wrap(f: Callable[..., Dict]) -> Callable[..., Action]:
         @wraps(f)