Refactor factory provider docs header

docs/providers/factory.rst

@@ -1,39 +1,29 @@
-Factory providers
+Factory provider
------------------
+----------------
 
 .. currentmodule:: dependency_injector.providers
 
-:py:class:`Factory` provider creates new instance of specified class on every 
+:py:class:`Factory` provider creates new objects.
-call.
-
-Nothing could be better than brief example:
-
-.. image:: /images/providers/factory.png
-    :width: 80%
-    :align: center
 
 .. literalinclude:: ../../examples/providers/factory.py
    :language: python
+   :lines: 3-
 
-Factory providers and __init__ injections
+The first argument of the ``Factory`` provider is a class, a factory function or a method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+that creates an object.
 
-:py:class:`Factory` takes a various number of positional and keyword arguments 
+The rest of the ``Factory`` positional and keyword arguments are the dependencies.
-that are used as ``__init__()`` injections. Every time, when 
+``Factory`` injects the dependencies every time when creates a new object.
-:py:class:`Factory` creates new one instance, positional and keyword 
-argument injections would be passed as instance arguments.
 
-Injections are done according to the next rules:
+Before injecting the dependencies ``Factory`` prepare them using the following rules:
 
-+ All providers (instances of :py:class:`Provider`) are called every time 
++ If the injection is a provider, it is called and the result of the call is injected.
-  when injection needs to be done.
++ If you need to inject the provider itself, you should use the ``.provider`` attribute. More at
-+ Providers could be injected "as is" (delegated), if it is defined obviously.
+  :ref:`factory_providers_delegation`.
-  Check out :ref:`factory_providers_delegation`.
++ All other dependencies are injected *"as is"*.
-+ All other injectable values are provided *"as is"*.
++ Positional context arguments are appended after ``Factory`` positional dependencies.
-+ Positional context arguments will be appended after :py:class:`Factory` 
++ Keyword context arguments have the priority over the ``Factory`` keyword dependencies with the same
-  positional injections.
+  name.
-+ Keyword context arguments have priority on :py:class:`Factory` keyword 
-  injections and will be merged over them.
 
 For example, if injectable value of injection is a :py:class:`Factory`, it 
 will provide new one instance (as a result of its call) every time, when 

examples/providers/factory.py

@@ -1,15 +1,15 @@
 """`Factory` providers example."""
 
-import collections
+from dependency_injector import providers
-
-import dependency_injector.providers as providers
 
 
-User = collections.namedtuple('User', [])
+class User:
+    ...
+
 
-# Factory provider creates new instance of specified class on every call.
 users_factory = providers.Factory(User)
 
-# Creating several User objects:
+
-user1 = users_factory()  # Same as: user1 = User()
+if __name__ == '__main__':
-user2 = users_factory()  # Same as: user2 = User()
+    user1 = users_factory()
+    user2 = users_factory()