Add docs and example

docs/providers/singleton.rst

@@ -20,13 +20,12 @@ returns it on the rest of the calls.
    :language: python
    :lines: 3-
 
-``Singleton`` provider handles an injection of the dependencies the same way like a
+``Singleton`` provider handles dependencies injection the same way like a :ref:`factory-provider`.
-:ref:`factory-provider`.
 
 .. note::
 
-   ``Singleton`` provider does dependencies injection only when creates the object. When the object
+   ``Singleton`` provider makes dependencies injection only when creates an object. When an object
-   is created and memorized ``Singleton`` provider just returns it without applying the injections.
+   is created and memorized ``Singleton`` provider just returns it without applying injections.
 
 Specialization of the provided type and abstract singletons work the same like like for the
 factories:
@@ -56,6 +55,21 @@ provider.
    Resetting of the memorized object clears the reference to it. Further object's lifecycle is
    managed by the garbage collector.
 
+You can use ``.reset()`` method with a context manager. Memorized instance will be reset on
+both entering and exiting a context.
+
+.. literalinclude:: ../../examples/providers/singleton_resetting_with.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 18-19
+
+Context manager ``.reset()`` returns resetting singleton provider. You can use it for aliasing.
+
+.. code-block:: python
+
+   with container.user_service.reset() as user_service:
+       ...
+
 Method ``.reset()`` resets only current provider. To reset all dependent singleton providers
 call ``.full_reset()`` method.
 
@@ -64,6 +78,13 @@ call ``.full_reset()`` method.
    :lines: 3-
    :emphasize-lines: 25
 
+Method ``.full_reset()`` supports context manager interface like ``.reset()`` does.
+
+.. code-block:: python
+
+   with container.user_service.full_reset() as user_service:
+       ...
+
 See also: :ref:`reset-container-singletons`.
 
 Using singleton with multiple threads

examples/providers/singleton_resetting_with.py

@@ -0,0 +1,27 @@
+"""`Singleton` provider resetting context manager example."""
+
+from dependency_injector import containers, providers
+
+
+class UserService:
+    ...
+
+
+class Container(containers.DeclarativeContainer):
+
+    user_service = providers.Singleton(UserService)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    user_service1 = container.user_service()
+
+    with container.user_service.reset():
+        user_service2 = container.user_service()
+
+    user_service3 = container.user_service()
+
+    assert user_service1 is not user_service2
+    assert user_service2 is not user_service3
+    assert user_service3 is not user_service1