feature #5283 [BestPractices] restructured text format for the installation instructions template (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[BestPractices] restructured text format for the installation instructions template

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | no
| Applies to    | all
| Fixed tickets |

Commits
-------

8845da0 [BestPractices] restructured text format for the installation instructions template

Author: wouterj

conf.py

@@ -23,6 +23,8 @@
 # adding PhpLexer
 from sphinx.highlighting import lexers
 from pygments.lexers.compiled import CLexer
+from pygments.lexers.special import TextLexer
+from pygments.lexers.text import RstLexer
 from pygments.lexers.web import PhpLexer
 
 # -- General configuration -----------------------------------------------------
@@ -97,14 +99,18 @@
 # -- Settings for symfony doc extension ---------------------------------------------------
 
 # enable highlighting for PHP code not between ``<?php ... ?>`` by default
+lexers['markdown'] = TextLexer()
 lexers['php'] = PhpLexer(startinline=True)
 lexers['php-annotations'] = PhpLexer(startinline=True)
 lexers['php-standalone'] = PhpLexer(startinline=True)
 lexers['php-symfony'] = PhpLexer(startinline=True)
+lexers['rst'] = RstLexer()
 lexers['varnish3'] = CLexer()
 lexers['varnish4'] = CLexer()
 
 config_block = {
+    'markdown': 'Markdown',
+    'rst': 'reStructuredText',
     'varnish3': 'Varnish 3',
     'varnish4': 'Varnish 4'
 }

cookbook/bundles/best_practices.rst

@@ -209,52 +209,102 @@ Installation Instructions
 In order to ease the installation of third-party bundles, consider using the
 following standardized instructions in your ``README.md`` file.
 
-.. code-block:: text
+.. configuration-block::
 
-    Installation
-    ============
+    .. code-block:: markdown
 
-    Step 1: Download the Bundle
-    ---------------------------
+        Installation
+        ============
 
-    Open a command console, enter your project directory and execute the
-    following command to download the latest stable version of this bundle:
+        Step 1: Download the Bundle
+        ---------------------------
 
-    ```bash
-    $ composer require <package-name> "~1"
-    ```
+        Open a command console, enter your project directory and execute the
+        following command to download the latest stable version of this bundle:
 
-    This command requires you to have Composer installed globally, as explained
-    in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
-    of the Composer documentation.
+        ```bash
+        $ composer require <package-name> "~1"
+        ```
 
-    Step 2: Enable the Bundle
-    -------------------------
+        This command requires you to have Composer installed globally, as explained
+        in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
+        of the Composer documentation.
 
-    Then, enable the bundle by adding the following line in the `app/AppKernel.php`
-    file of your project:
+        Step 2: Enable the Bundle
+        -------------------------
 
-    ```php
-    <?php
-    // app/AppKernel.php
+        Then, enable the bundle by adding the following line in the `app/AppKernel.php`
+        file of your project:
 
-    // ...
-    class AppKernel extends Kernel
-    {
-        public function registerBundles()
+        ```php
+        <?php
+        // app/AppKernel.php
+
+        // ...
+        class AppKernel extends Kernel
         {
-            $bundles = array(
-                // ...
+            public function registerBundles()
+            {
+                $bundles = array(
+                    // ...
+
+                    new <vendor>\<bundle-name>\<bundle-long-name>(),
+                );
 
-                new <vendor>\<bundle-name>\<bundle-long-name>(),
-            );
+                // ...
+            }
 
             // ...
         }
+        ```
 
-        // ...
-    }
-    ```
+    .. code-block:: rst
+
+        Installation
+        ============
+
+        Step 1: Download the Bundle
+        ---------------------------
+
+        Open a command console, enter your project directory and execute the
+        following command to download the latest stable version of this bundle:
+
+        .. code-block:: bash
+
+            $ composer require <package-name> "~1"
+
+        This command requires you to have Composer installed globally, as explained
+        in the `installation chapter`_ of the Composer documentation.
+
+        Step 2: Enable the Bundle
+        -------------------------
+
+        Then, enable the bundle by adding the following line in the ``app/AppKernel.php``
+        file of your project:
+
+        .. code-block:: php
+
+            <?php
+            // app/AppKernel.php
+
+            // ...
+            class AppKernel extends Kernel
+            {
+                public function registerBundles()
+                {
+                    $bundles = array(
+                        // ...
+
+                        new <vendor>\<bundle-name>\<bundle-long-name>(),
+                    );
+
+                    // ...
+                }
+
+                // ...
+            }
+
+        .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
 
 This template assumes that your bundle is in its ``1.x`` version. If not, change
 the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)