From cea843160ccc764338eef273635b83d14dfd307f Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <rmogilatov@gmail.com>
Date: Mon, 23 Nov 2015 15:03:30 +0200
Subject: [PATCH] Update static providers docs, including API, and examples

---
 dependency_injector/providers.py | 70 ++++++++++++++++++++++++++++----
 docs/providers/static.rst        | 15 ++++---
 examples/providers/static.py     | 10 ++---
 3 files changed, 75 insertions(+), 20 deletions(-)

diff --git a/dependency_injector/providers.py b/dependency_injector/providers.py
index f5a9055e..7b89a192 100644
--- a/dependency_injector/providers.py
+++ b/dependency_injector/providers.py
@@ -277,6 +277,17 @@ class Singleton(Provider):
 
     :py:class:`Singleton` is thread-safe and could be used in multithreading
     environment without any negative impact.
+
+    Retrieving of provided instance can be performed via calling
+    :py:class:`Singleton` object:
+
+    .. code-block:: python
+
+        singleton = Singleton(SomeClass,
+                              some_arg1=1,
+                              some_arg2=2)
+        some_object = singleton()
+
     """
 
     __slots__ = ('instance', 'factory')
@@ -405,38 +416,79 @@ class ExternalDependency(Provider):
 
 
 class StaticProvider(Provider):
-    """Static provider.
+    """:py:class:`StaticProvider` returns provided instance "as is".
 
-    Static provider is base implementation that provides exactly the same as
-    it got on input.
+    :py:class:`StaticProvider` is base implementation that provides exactly
+    the same as it got on input.
     """
 
     __slots__ = ('provides',)
 
     def __init__(self, provides):
-        """Initializer."""
+        """Initializer.
+
+        :param provides: value that have to be provided.
+        :type provides: object
+        """
         self.provides = provides
+        """Value that have to be provided.
+
+        :type: object
+        """
         super(StaticProvider, self).__init__()
 
     def _provide(self, *args, **kwargs):
-        """Return provided instance."""
+        """Return provided instance.
+
+        :param args: tuple of context positional arguments
+        :type args: tuple[object]
+
+        :param kwargs: dictionary of context keyword arguments
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
         return self.provides
 
 
 class Class(StaticProvider):
-    """Class provider provides class."""
+    """:py:class:`Class` returns provided class "as is".
+
+    .. code-block:: python
+
+        cls_provider = Class(object)
+        object_cls = cls_provider()
+    """
 
 
 class Object(StaticProvider):
-    """Object provider provides object."""
+    """:py:class:`Object` returns provided object "as is".
+
+    .. code-block:: python
+
+        object_provider = Object(object())
+        object_instance = object_provider()
+    """
 
 
 class Function(StaticProvider):
-    """Function provider provides function."""
+    """:py:class:`Function` returns provided function "as is".
+
+    .. code-block:: python
+
+        function_provider = Function(len)
+        len_function = function_provider()
+    """
 
 
 class Value(StaticProvider):
-    """Value provider provides value."""
+    """:py:class:`Value` returns provided value "as is".
+
+    .. code-block:: python
+
+        value_provider = Value(31337)
+        value = value_provider()
+    """
 
 
 class Callable(Provider):
diff --git a/docs/providers/static.rst b/docs/providers/static.rst
index f4c3394e..66296bed 100644
--- a/docs/providers/static.rst
+++ b/docs/providers/static.rst
@@ -1,16 +1,19 @@
 Static providers
 ----------------
 
+.. module:: dependency_injector.providers
+
 Static providers are family of providers that return their values "as is".
 There are four types of static providers:
 
-    - ``di.Class``
-    - ``di.Object``
-    - ``di.Function``
-    - ``di.Value``
+    - :py:class:`Class`
+    - :py:class:`Object`
+    - :py:class:`Function`
+    - :py:class:`Value`
 
-All of them have the same behaviour, but usage of anyone is predicted by
-readability and providing object's type.
+All of them have the same behaviour (inherited from 
+:py:class:`StaticProvider`), but usage of any is predicted by readability 
+and providing object's type.
 
 Example:
 
diff --git a/examples/providers/static.py b/examples/providers/static.py
index 69726eb6..7fa5460b 100644
--- a/examples/providers/static.py
+++ b/examples/providers/static.py
@@ -1,20 +1,20 @@
 """Static providers example."""
 
-import dependency_injector as di
+from dependency_injector import providers
 
 
 # Provides class - `object`:
-cls_provider = di.Class(object)
+cls_provider = providers.Class(object)
 assert cls_provider() is object
 
 # Provides object - `object()`:
-object_provider = di.Object(object())
+object_provider = providers.Object(object())
 assert isinstance(object_provider(), object)
 
 # Provides function - `len`:
-function_provider = di.Function(len)
+function_provider = providers.Function(len)
 assert function_provider() is len
 
 # Provides value - `123`:
-value_provider = di.Value(123)
+value_provider = providers.Value(123)
 assert value_provider() == 123