minor #8310 [DI] add docs for new namespace option (kbond, javiereguiluz)

This PR was merged into the 3.4 branch.

Discussion
----------

[DI] add docs for new namespace option

| Q             | A
| ------------- | ---
| Doc fix?       | no
| New docs?      | yes
| Applies to?  | 3.4
| Fixed tickets?    | symfony/symfony#23991

Commits
-------

f395dad Reworded and turned the sidebar into a section
16e0cc7 [DI] add docs for new namespace option

Author: javiereguiluz

service_container.rst

@@ -371,7 +371,7 @@ made. To do that, you create a new class::
                 ->addPart(
                     'Someone just updated the site. We told them: '.$happyMessage
                 );
-            
+
             return $this->mailer->send($message) > 0;
         }
     }
@@ -389,7 +389,7 @@ you can use the service immediately::
         if ($siteUpdateManager->notifyOfSiteUpdate()) {
             $this->addFlash('success', 'Notification mail was sent successfully.');
         }
-        
+
         // ...
     }
 
@@ -954,6 +954,41 @@ them will not cause the container to be rebuilt.
     means that all classes are "available to be *used* as services" without needing
     to be manually configured.
 
+Multiple Service Definitions Using the Same Namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+    The ``namespace`` option in the YAML configuration was introduced in Symfony 3.4.
+
+If you define services using the YAML config format, the PHP namespace is used
+as the key of each configuration, so you can't define different service configs
+for classes under the same namespace:
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    services:
+        App\Domain\:
+            resource: '../../src/Domain/*'
+            # ...
+
+In order to have multiple definitions, add the ``namespace`` option and use any
+unique string as the key of each service config:
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            command_handlers:
+                namespace: App\Domain\
+                resource: '../../src/Domain/*/CommandHandler'
+                tags: [command_handler]
+
+            event_subscribers:
+                namespace: App\Domain\
+                resource: '../../src/Domain/*/EventSubscriber'
+                tags: [event_subscriber]
+
 .. _services-explicitly-configure-wire-services:
 
 Explicitly Configuring Services and Arguments