Merge pull request symfony#1085 from kbond/config-dump

added config:dump-reference docs

book/page_creation.rst

@@ -251,10 +251,10 @@ application should greet you:
     .. code-block:: text
 
         http://localhost/app.php/hello/Ryan
-    
+
     If you get an error, it's likely because you need to clear your cache
     by running:
-    
+
     .. code-block:: bash
 
         php app/console cache:clear --env=prod --no-debug
@@ -723,7 +723,7 @@ format you prefer:
         imports:
             - { resource: parameters.yml }
             - { resource: security.yml }
-        
+
         framework:
             secret:          %secret%
             charset:         UTF-8
@@ -744,7 +744,7 @@ format you prefer:
             <import resource="parameters.yml" />
             <import resource="security.yml" />
         </imports>
-        
+
         <framework:config charset="UTF-8" secret="%secret%">
             <framework:router resource="%kernel.root_dir%/config/routing.xml" />
             <!-- ... -->
@@ -803,6 +803,26 @@ options of each feature.
 
     * *PHP*: Very powerful but less readable than standard configuration formats.
 
+Default Configuration Dump
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.1
+    The ``config:dump-reference`` command was added in Symfony 2.1
+
+You can dump the default configuration for a bundle in yaml to the console using
+the ``config:dump-reference`` command.  Here is an example of dumping the default
+FrameworkBundle configuration:
+
+.. code-block:: text
+
+    app/console config:dump-reference FrameworkBundle
+
+.. note::
+
+    See the cookbook article: :doc:`How to expose a Semantic Configuration for
+    a Bundle</cookbook/bundles/extension>` for information on adding
+    configuration for your own bundle.
+
 .. index::
    single: Environments; Introduction
 

cookbook/bundles/extension.rst

@@ -18,19 +18,19 @@ as integration of other related components:
 .. configuration-block::
 
     .. code-block:: yaml
-    
+
         framework:
             # ...
             form:            true
 
     .. code-block:: xml
-    
+
         <framework:config>
             <framework:form />
         </framework:config>
 
     .. code-block:: php
-    
+
         $container->loadFromExtension('framework', array(
             // ...
             'form'            => true,
@@ -304,7 +304,7 @@ option is passed and set to true::
         // prepare your $config variable
 
         $loader = new XmlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
-        
+
         if (isset($config['enabled']) && $config['enabled']) {
             $loader->load('services.xml');
         }
@@ -470,7 +470,7 @@ that an unsupported option was passed::
         $processor = new Processor();
         $configuration = new Configuration();
         $config = $processor->processConfiguration($configuration, $configs);
-    
+
         // ...
     }
 
@@ -484,6 +484,54 @@ normalization and advanced merging. The best way to see this in action is
 to checkout out some of the core Configuration classes, such as the one from
 the `FrameworkBundle Configuration`_ or the `TwigBundle Configuration`_.
 
+Default Configuration Dump
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.1
+    The ``config:dump-reference`` command was added in Symfony 2.1
+
+The ``config:dump-reference`` command allows a bundle's default configuration to
+be output to the console in yaml.
+
+As long as your bundle's configuration is located in the standard location
+(``YourBundle\DependencyInjection\Configuration``) and does not have a
+``__constructor()`` it will work automatically.  If you have a something
+different your ``Extension`` class will have to override the
+``Extension::getConfiguration()`` method.  Have it return an instance of your
+``Configuration``.
+
+Comments and examples can be added to your configuration nodes using the
+``->setInfo()`` and ``->setExample()`` methods::
+
+    // src/Acme/HelloBundle/DependencyExtension/Configuration.php
+    namespace Acme\HelloBundle\DependencyInjection;
+
+    use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+    use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+    class Configuration implements ConfigurationInterface
+    {
+        public function getConfigTreeBuilder()
+        {
+            $treeBuilder = new TreeBuilder();
+            $rootNode = $treeBuilder->root('acme_hello');
+
+            $rootNode
+                ->children()
+                    ->scalarNode('my_type')
+                        ->defaultValue('bar')
+                        ->setInfo('what my_type configures')
+                        ->setExample('example setting')
+                    ->end()
+                ->end()
+            ;
+
+            return $treeBuilder;
+        }
+
+This text appears as yaml comments in the output of the ``config:dump-reference``
+command.
+
 .. index::
    pair: Convention; Configuration