Merge branch '4.0'

* 4.0:
  Use the shorthand notation when applicable

Author: javiereguiluz

best_practices/business-logic.rst

@@ -43,9 +43,7 @@ as Twig extensions, event subscribers, etc.
 
 The blog application needs a utility that can transform a post title (e.g.
 "Hello World") into a slug (e.g. "hello-world") to include it as part of the
-post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``:
-
-.. code-block:: php
+post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``::
 
     // src/Utils/Slugger.php
     namespace App\Utils;
@@ -69,9 +67,7 @@ simply ``Slugger::class`` if the class is already imported in your code).
     case, use a snake case id).
 
 Now you can use the custom slugger in any other service or controller class,
-such as the ``AdminController``:
-
-.. code-block:: php
+such as the ``AdminController``::
 
     use App\Utils\Slugger;
 
@@ -152,9 +148,7 @@ PHP and annotations.
     Use annotations to define the mapping information of the Doctrine entities.
 
 Annotations are by far the most convenient and agile way of setting up and
-looking for mapping information:
-
-.. code-block:: php
+looking for mapping information::
 
     namespace App\Entity;
 
@@ -233,9 +227,7 @@ the following command to install the Doctrine fixtures bundle:
     $ composer require "doctrine/doctrine-fixtures-bundle"
 
 Then, this bundle is enabled automatically, but only for the ``dev`` and
-``test`` environments:
-
-.. code-block:: php
+``test`` environments::
 
     // config/bundles.php
 

best_practices/configuration.rst

@@ -135,9 +135,7 @@ Constants can be used for example in your Twig templates thanks to the
     </p>
 
 And Doctrine entities and repositories can now easily access these values,
-whereas they cannot access the container parameters:
-
-.. code-block:: php
+whereas they cannot access the container parameters::
 
     namespace App\Repository;
 

best_practices/controllers.rst

@@ -98,9 +98,7 @@ What does the Controller look like
 ----------------------------------
 
 Considering all this, here is an example of what the controller should look like
-for the homepage of our app:
-
-.. code-block:: php
+for the homepage of our app::
 
     namespace App\Controller;
 
@@ -154,9 +152,7 @@ to automatically query for an entity and pass it as an argument to your controll
     Use the ParamConverter trick to automatically query for Doctrine entities
     when it's simple and convenient.
 
-For example:
-
-.. code-block:: php
+For example::
 
     use App\Entity\Post;
     use Symfony\Component\Routing\Annotation\Route;
@@ -187,9 +183,7 @@ The above example works without any configuration because the wildcard name
 ``{id}`` matches the name of the property on the entity. If this isn't true, or
 if you have even more complex logic, the easiest thing to do is just query for
 the entity manually. In our application, we have this situation in
-``CommentController``:
-
-.. code-block:: php
+``CommentController``::
 
     /**
      * @Route("/comment/{postSlug}/new", name="comment_new")
@@ -208,9 +202,7 @@ the entity manually. In our application, we have this situation in
     }
 
 You can also use the ``@ParamConverter`` configuration, which is infinitely
-flexible:
-
-.. code-block:: php
+flexible::
 
     use App\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

best_practices/forms.rst

@@ -80,9 +80,7 @@ makes them easier to re-use later.
 The Symfony Form component allows you to add buttons as fields on your form.
 This is a nice way to simplify the template that renders your form. But if you
 add the buttons directly in your form class, this would effectively limit the
-scope of that form:
-
-.. code-block:: php
+scope of that form::
 
     class PostType extends AbstractType
     {
@@ -164,9 +162,7 @@ can control *how* the form renders at a global level using form theming.
 Handling Form Submits
 ---------------------
 
-Handling a form submit usually follows a similar template:
-
-.. code-block:: php
+Handling a form submit usually follows a similar template::
 
     public function new(Request $request)
     {

best_practices/security.rst

@@ -134,9 +134,7 @@ Using Expressions for Complex Security Restrictions
 If your security logic is a little bit more complex, you can use an :doc:`expression </components/expression_language>`
 inside ``@Security``. In the following example, a user can only access the
 controller if their email matches the value returned by the ``getAuthorEmail()``
-method on the ``Post`` object:
-
-.. code-block:: php
+method on the ``Post`` object::
 
     use App\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
@@ -167,9 +165,7 @@ need to repeat the expression code using Twig syntax:
     {% endif %}
 
 The easiest solution - if your logic is simple enough - is to add a new method
-to the ``Post`` entity that checks if a given user is its author:
-
-.. code-block:: php
+to the ``Post`` entity that checks if a given user is its author::
 
     // src/Entity/Post.php
     // ...
@@ -189,9 +185,7 @@ to the ``Post`` entity that checks if a given user is its author:
         }
     }
 
-Now you can reuse this method both in the template and in the security expression:
-
-.. code-block:: php
+Now you can reuse this method both in the template and in the security expression::
 
     use App\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
@@ -222,9 +216,7 @@ Checking Permissions without @Security
 The above example with ``@Security`` only works because we're using the
 :ref:`ParamConverter <best-practices-paramconverter>`, which gives the expression
 access to the ``post`` variable. If you don't use this, or have some other
-more advanced use-case, you can always do the same security check in PHP:
-
-.. code-block:: php
+more advanced use-case, you can always do the same security check in PHP::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
@@ -271,9 +263,7 @@ If your security logic is complex and can't be centralized into a method like
 all cases.
 
 First, create a voter class. The following example shows a voter that implements
-the same ``getAuthorEmail()`` logic you used above:
-
-.. code-block:: php
+the same ``getAuthorEmail()`` logic you used above::
 
     namespace App\Security;
 
@@ -345,9 +335,7 @@ your application will :ref:`autoconfigure <services-autoconfigure>` your securit
 voter and inject an ``AccessDecisionManagerInterface`` instance into it thanks to
 :doc:`autowiring </service_container/autowiring>`.
 
-Now, you can use the voter with the ``@Security`` annotation:
-
-.. code-block:: php
+Now, you can use the voter with the ``@Security`` annotation::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
@@ -359,9 +347,7 @@ Now, you can use the voter with the ``@Security`` annotation:
     }
 
 You can also use this directly with the ``security.authorization_checker`` service or
-via the even easier shortcut in a controller:
-
-.. code-block:: php
+via the even easier shortcut in a controller::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")

best_practices/templates.rst

@@ -75,9 +75,7 @@ to define one single method to transform Markdown content into HTML::
 
 Next, create a new Twig extension and define a filter called ``md2html`` using
 the ``TwigFilter`` class. Inject the newly defined ``Markdown`` class in the
-constructor of the Twig extension:
-
-.. code-block:: php
+constructor of the Twig extension::
 
     namespace App\Twig;
 

best_practices/tests.rst

@@ -79,9 +79,7 @@ generator service:
     generator.
 
 Consider the following functional test that uses the ``router`` service to
-generate the URL of the tested page:
-
-.. code-block:: php
+generate the URL of the tested page::
 
     // ...
     private $router; // consider that this holds the Symfony router service

components/config/definition.rst

@@ -452,9 +452,7 @@ Documenting the Option
 
 All options can be documented using the
 :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::info`
-method.
-
-.. code-block:: php
+method::
 
     $rootNode
         ->children()

components/dom_crawler.rst

@@ -248,9 +248,7 @@ The crawler supports multiple ways of adding the content::
 
 As the Crawler's implementation is based on the DOM extension, it is also able
 to interact with native :phpclass:`DOMDocument`, :phpclass:`DOMNodeList`
-and :phpclass:`DOMNode` objects:
-
-.. code-block:: php
+and :phpclass:`DOMNode` objects::
 
     $domDocument = new \DOMDocument();
     $domDocument->loadXml('<root><node /><node /></root>');

components/expression_language/extending.rst

@@ -65,9 +65,7 @@ This interface requires one method:
 :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`,
 which returns an array of expression functions (instances of
 :class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to
-register.
-
-.. code-block:: php
+register::
 
     use Symfony\Component\ExpressionLanguage\ExpressionFunction;
     use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;

components/process.rst

@@ -369,9 +369,7 @@ Process Pid
 -----------
 
 You can access the `pid`_ of a running process with the
-:method:`Symfony\\Component\\Process\\Process::getPid` method.
-
-.. code-block:: php
+:method:`Symfony\\Component\\Process\\Process::getPid` method::
 
     use Symfony\Component\Process\Process;
 

components/templating.rst

@@ -187,9 +187,7 @@ takes a list of engines and acts just like a normal templating engine. The
 only difference is that it delegates the calls to one of the other engines. To
 choose which one to use for the template, the
 :method:`EngineInterface::supports() <Symfony\\Component\\Templating\\EngineInterface::supports>`
-method is used.
-
-.. code-block:: php
+method is used::
 
     use Acme\Templating\CustomEngine;
     use Symfony\Component\Templating\PhpEngine;

components/translation.rst

@@ -29,9 +29,7 @@ catalogs*).
 Configuration
 ~~~~~~~~~~~~~
 
-The constructor of the ``Translator`` class needs one argument: The locale.
-
-.. code-block:: php
+The constructor of the ``Translator`` class needs one argument: The locale::
 
     use Symfony\Component\Translation\Translator;
 

components/yaml.rst

@@ -96,9 +96,7 @@ Reading YAML Contents
 ~~~~~~~~~~~~~~~~~~~~~
 
 The :method:`Symfony\\Component\\Yaml\\Yaml::parse` method parses a YAML
-string and converts it to a PHP array:
-
-.. code-block:: php
+string and converts it to a PHP array::
 
     use Symfony\Component\Yaml\Yaml;
 
@@ -108,9 +106,7 @@ string and converts it to a PHP array:
 If an error occurs during parsing, the parser throws a
 :class:`Symfony\\Component\\Yaml\\Exception\\ParseException` exception
 indicating the error type and the line in the original YAML string where the
-error occurred:
-
-.. code-block:: php
+error occurred::
 
     use Symfony\Component\Yaml\Exception\ParseException;
 
@@ -138,9 +134,7 @@ Writing YAML Files
 ~~~~~~~~~~~~~~~~~~
 
 The :method:`Symfony\\Component\\Yaml\\Yaml::dump` method dumps any PHP
-array to its YAML representation:
-
-.. code-block:: php
+array to its YAML representation::
 
     use Symfony\Component\Yaml\Yaml;
 
@@ -172,9 +166,7 @@ representation:
 
 The second argument of the :method:`Symfony\\Component\\Yaml\\Yaml::dump`
 method customizes the level at which the output switches from the expanded
-representation to the inline one:
-
-.. code-block:: php
+representation to the inline one::
 
     echo Yaml::dump($array, 1);
 

components/yaml/yaml_format.rst

@@ -177,9 +177,7 @@ Sequences use a dash followed by a space:
     - Perl
     - Python
 
-The previous YAML file is equivalent to the following PHP code:
-
-.. code-block:: php
+The previous YAML file is equivalent to the following PHP code::
 
     array('PHP', 'Perl', 'Python');
 
@@ -191,9 +189,7 @@ Mappings use a colon followed by a space (``:`` ) to mark each key/value pair:
     MySQL: 5.1
     Apache: 2.2.20
 
-which is equivalent to this PHP code:
-
-.. code-block:: php
+which is equivalent to this PHP code::
 
     array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
 
@@ -220,9 +216,7 @@ YAML uses indentation with one or more spaces to describe nested collections:
       PHP:    5.2
       Propel: 1.3
 
-The above YAML is equivalent to the following PHP code:
-
-.. code-block:: php
+The above YAML is equivalent to the following PHP code::
 
     array(
         'symfony 1.0' => array(

configuration/environments.rst

@@ -33,7 +33,7 @@ In reality, each environment differs only somewhat from others. This means that
 all environments share a large base of common configurations. This configuration
 is put in files directly in the ``config/packages/`` directory.
 
-The location of these files is defined by the application's Kernel::
+The location of these files is defined by the application's kernel::
 
     // src/Kernel.php
 

configuration/external_parameters.rst

@@ -61,7 +61,7 @@ This variable is referenced in the service container configuration using
 
         </container>
 
-    .. code-block:: php
+    ::
 
         // config/packages/doctrine.php
         $container->loadFromExtension('doctrine', array(

contributing/documentation/standards.rst

@@ -13,8 +13,8 @@ Sphinx
 * Each line should break approximately after the first word that crosses the
   72nd character (so most lines end up being 72-78 characters);
 * The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP
-  code block (read `the Sphinx documentation`_ to see when you should use the
-  shorthand);
+  code block unless it results in the marker being on its own line (read
+  `the Sphinx documentation`_ to see when you should use the shorthand);
 * Inline hyperlinks are **not** used. Separate the link and their target
   definition, which you add on the bottom of the page;
 * Inline markup should be closed on the same line as the open-string;