Add docs on @containers.copy() decorator

Author: rmk135

docs/containers/copying.rst

@@ -0,0 +1,14 @@
+Container copying
+-----------------
+
+You can create declarative container copies using ``@containers.copy()`` decorator.
+
+.. literalinclude:: ../../examples/containers/declarative_copy_decorator.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 18-22
+
+Decorator ``@containers.copy()`` copies providers from source container to destination container.
+Destination container provider will replace source provider, if names match.
+
+.. disqus::

docs/containers/index.rst

@@ -23,6 +23,7 @@ Containers module API docs - :py:mod:`dependency_injector.containers`.
     dynamic
     specialization
     overriding
+    copying
     reset_singletons
     check_dependencies
     traversal

docs/main/changelog.rst

@@ -9,6 +9,7 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
+- Add docs on ``@containers.copy()`` decorator.
 - Refactor ``@containers.copy()`` decorator.
 - Refactor async mode support in containers module.
 

examples/containers/declarative_copy_decorator.py

@@ -0,0 +1,31 @@
+"""Declarative container provider copying with ``@copy()`` decorator."""
+
+import sqlite3
+from unittest import mock
+
+from dependency_injector import containers, providers
+
+
+class Service:
+    def __init__(self, db):
+        self.db = db
+
+
+class SourceContainer(containers.DeclarativeContainer):
+
+    database = providers.Singleton(sqlite3.connect, ':memory:')
+    service = providers.Factory(Service, db=database)
+
+
+# Copy ``SourceContainer`` providers into ``DestinationContainer``:
+@containers.copy(SourceContainer)
+class DestinationContainer(SourceContainer):
+
+    database = providers.Singleton(mock.Mock)
+
+
+if __name__ == '__main__':
+    container = DestinationContainer()
+
+    service = container.service()
+    assert isinstance(service.db, mock.Mock)