diff --git a/contributing/code/bugs.rst b/contributing/code/bugs.rst index 4ff411cb23a..35f38827395 100644 --- a/contributing/code/bugs.rst +++ b/contributing/code/bugs.rst @@ -5,8 +5,9 @@ Whenever you find a bug in Symfony2, we kindly ask you to report it. It helps us make a better Symfony2. .. caution:: - If you think you've found a security issue, please use the special - doc:`procedure ` instead. + + If you think you've found a security issue, please use the special + doc:`procedure ` instead. Before submitting a bug: diff --git a/contributing/code/license.rst b/contributing/code/license.rst index ba7e7345e92..2fa29c77f60 100644 --- a/contributing/code/license.rst +++ b/contributing/code/license.rst @@ -5,11 +5,11 @@ Symfony2 is released under the MIT license. According to `Wikipedia`_: - "It is a permissive license, meaning that it permits reuse within - proprietary software on the condition that the license is distributed with - that software. The license is also GPL-compatible, meaning that the GPL - permits combination and redistribution with software that uses the MIT - License." + "It is a permissive license, meaning that it permits reuse within + proprietary software on the condition that the license is distributed with + that software. The license is also GPL-compatible, meaning that the GPL + permits combination and redistribution with software that uses the MIT + License." The License ----------- diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index 6e0236e2fea..0eb735db22c 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -24,8 +24,9 @@ Set up your user information with your real name and a working email address: $ git config --global user.email you@example.com .. tip:: - If you are new to Git, we highly recommend you to read the excellent and free - `ProGit`_ book. + + If you are new to Git, we highly recommend you to read the excellent and + free `ProGit`_ book. Get the Symfony2 code source: @@ -61,11 +62,12 @@ topic branch: $ git checkout -b BRANCH_NAME .. tip:: - Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the ticket - number is a good convention for bug fixes). + + Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the + ticket number is a good convention for bug fixes). The above command automatically switches the code to the newly created branch -(check the branch you are working on with `git branch`.) +(check the branch you are working on with `git branch`). Work on the code as much as you want and commit as much as you want; but keep in mind the following: @@ -82,11 +84,13 @@ in mind the following: * Write good commit messages. .. tip:: - A good commit message is composed of a summary (the first line), optionally - followed by a blank line and a more detailed description. The summary should - start with the Component you are working on in square brackets - (`[DependencyInjection]`, `[FrameworkBundle]`, ...). Use a verb (`fixed ...`, - `added ...`, ...) to start the summary and don't add a period at the end. + + A good commit message is composed of a summary (the first line), optionally + followed by a blank line and a more detailed description. The summary + should start with the Component you are working on in square brackets + (`[DependencyInjection]`, `[FrameworkBundle]`, ...). Use a verb + (`fixed ...`, `added ...`, ...) to start the summary and don't add a period + at the end. Submitting a Patch ------------------ diff --git a/contributing/code/security.rst b/contributing/code/security.rst index 42847b1ac69..e73d786e054 100644 --- a/contributing/code/security.rst +++ b/contributing/code/security.rst @@ -17,4 +17,5 @@ confirmed, the core-team works on a solution following these steps: 5. Publish the post on the official Symfony blog. .. note:: - While we are working on a patch, please do not reveal the issue publicly. + + While we are working on a patch, please do not reveal the issue publicly. diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst index e687e2e31d5..3ed9ac5f940 100755 --- a/contributing/code/tests.rst +++ b/contributing/code/tests.rst @@ -39,7 +39,8 @@ To install them all, run the `install_vendors.sh` script: $ sh install_vendors.sh .. note:: - Note that the script takes some time to finish. + + Note that the script takes some time to finish. After installation, you can update the vendors anytime with the `update_vendors.sh` script: @@ -64,8 +65,9 @@ The output should display `OK`. If not, you need to figure out what's going on and if the tests are broken because of your modifications. .. tip:: - Run the test suite before applying your modifications to check that they run - fine on your configuration. + + Run the test suite before applying your modifications to check that they + run fine on your configuration. Code Coverage ------------- @@ -81,7 +83,8 @@ Check the code coverage by opening the generated `cov/index.html` page in a browser. .. tip:: - The code coverage only works if you have XDebug enabled and all dependencies - installed. + + The code coverage only works if you have XDebug enabled and all + dependencies installed. .. _install: http://www.phpunit.de/manual/current/en/installation.html diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index e5e74da09a0..6c95b5e2043 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -49,7 +49,8 @@ the highlighted pseudo-language: foobar(); ?> .. note:: - A list of supported languages is available on the `Pygments website`_. + + A list of supported languages is available on the `Pygments website`_. Configuration Blocks ~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 91028e683e2..c031b8b9db6 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -25,8 +25,9 @@ If you want to submit a patch, clone the official documentation repository: $ git clone git://github.com/symfony/symfony-docs.git .. note:: - The Symfony2 documentation is licensed under a Creative Commons - Attribution-Share Alike 3.0 Unported :doc:`License `. + + The Symfony2 documentation is licensed under a Creative Commons + Attribution-Share Alike 3.0 Unported :doc:`License `. Reporting an Issue ------------------ diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index 12015d3a0d5..e62be6546c7 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -21,8 +21,9 @@ for. Here is the list of the official *master* repositories: * *Romanian*: http://github.com/sebastian-ionescu/symfony-docs-ro .. note:: - If you want to contribute translations for a new language, read the - :ref:`dedicated section `. + + If you want to contribute translations for a new language, read the + :ref:`dedicated section `. Joining the Translation Team ---------------------------- @@ -76,7 +77,8 @@ reorganized, ...). The translation team need to closely follow the English repository and apply changes to the translated documents as soon as possible. .. caution:: - Non maintained languages are removed from the official list of - repositories as obsolete documentation is dangerous. + + Non maintained languages are removed from the official list of + repositories as obsolete documentation is dangerous. .. _Symfony docs mailing-list: http://groups.google.com/group/symfony-docs diff --git a/guides/bundles/best_practices.rst b/guides/bundles/best_practices.rst index 10709decbf8..3d84d8acf60 100644 --- a/guides/bundles/best_practices.rst +++ b/guides/bundles/best_practices.rst @@ -25,8 +25,9 @@ A bundle is also a PHP namespace, composed of several segments: * The **bundle name**. .. caution:: - The vendor namespace and the category namespaces are only possible as of - Symfony2 PR3. + + The vendor namespace and the category namespaces are only possible as of + Symfony2 PR3. The bundle name must follow these simple rules: @@ -76,8 +77,9 @@ The following files are mandatory: * ``Resources/doc/index.rst``: The root file for the Bundle documentation. .. note:: - These conventions ensure that automated tools can rely on this default - structure to work. + + These conventions ensure that automated tools can rely on this default + structure to work. The depth of sub-directories should be kept to the minimal for most used classes and files (2 levels at a maximum). More levels can be defined for @@ -166,9 +168,10 @@ extend :class:`Symfony\\Foundation\\DependencyInjection\\ContainerAware` instead. .. note:: + If you have a look at :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` - methods, you will see that they are only nice shortcuts to ease the learning - curve. + methods, you will see that they are only nice shortcuts to ease the + learning curve. Templates --------- @@ -178,8 +181,9 @@ must not provide a main layout, but extend a default ``base`` template (which must provide two slots: ``content`` and ``head``). .. note:: - The only other template engine supported is Twig, but only for specific - cases. + + The only other template engine supported is Twig, but only for specific + cases. Translation Files ----------------- diff --git a/guides/bundles/configuration.rst b/guides/bundles/configuration.rst index 78d44d5ac4a..7e7f5f07d7c 100644 --- a/guides/bundles/configuration.rst +++ b/guides/bundles/configuration.rst @@ -140,8 +140,9 @@ configuration file: $container->loadFromExtension('hello', 'config', array()); .. note:: - You can create as many ``xxxLoad()`` methods as you want to define more - configuration blocks for your extension. + + You can create as many ``xxxLoad()`` methods as you want to define more + configuration blocks for your extension. Parsing a Configuration ~~~~~~~~~~~~~~~~~~~~~~~ @@ -219,8 +220,9 @@ The global parameters are the following: * ``kernel.charset`` .. caution:: - All parameter and service names starting with a ``_`` are reserved for the - framework, and new ones must not be defined by bundles. + + All parameter and service names starting with a ``_`` are reserved for the + framework, and new ones must not be defined by bundles. .. index:: pair: Convention; Configuration @@ -282,5 +284,6 @@ method:: } .. caution:: - Symfony2 tries to be as explicit as possible. So, registering a default - configuration automatically is probably not a good idea. + + Symfony2 tries to be as explicit as possible. So, registering a default + configuration automatically is probably not a good idea. diff --git a/guides/cache/http.rst b/guides/cache/http.rst index c1cfa3db2b1..cbff428df45 100644 --- a/guides/cache/http.rst +++ b/guides/cache/http.rst @@ -60,7 +60,7 @@ header when none is set by the developer by following these rules: * But if at least one ``Cache-Control`` directive is set, and no 'public' or ``private`` directives have been explicitly added, Symfony2 adds the - ``private`` directive automatically (except when ``s-maxage`` is set.) + ``private`` directive automatically (except when ``s-maxage`` is set). .. tip:: @@ -232,7 +232,7 @@ issue. Under this model, you mainly save bandwidth as the representation is not sent twice to the same client (a 304 response is sent instead). But if you design your application carefully, you might be able to get the bare minimum data needed to send a 304 response and save CPU also; and if needed, perform -the more heavy tasks (see below for an implementation example.) +the more heavy tasks (see below for an implementation example). .. index:: single: Cache; Etag header @@ -399,7 +399,7 @@ Public vs Private Responses As explained at the beginning of this document, Symfony2 is very conservative and makes all Responses private by default (the exact rules are described -there.) +there). If you want to use a shared cache, you must remember to explicitly add the ``public`` directive to ``Cache-Control``:: @@ -619,7 +619,7 @@ standalone is ``false``. Symfony2 detects if a gateway cache supports ESI via another Akamaï specification that is supported out of the box by the Symfony2 reverse - proxy (a working configuration for Varnish is also provided below.) + proxy (a working configuration for Varnish is also provided below). For the ESI include tag to work properly, you must define the ``_internal`` route: diff --git a/guides/doctrine/dbal/overview.rst b/guides/doctrine/dbal/overview.rst index 974d0b985be..c16d5b3ee40 100644 --- a/guides/doctrine/dbal/overview.rst +++ b/guides/doctrine/dbal/overview.rst @@ -9,8 +9,9 @@ sits on top of `PDO`_ and offers an intuitive and flexible API for communicating with the most popular relational databases that exist today! .. tip:: - You can read more about the Doctrine DBAL on the official `documentation`_ - website. + + You can read more about the Doctrine DBAL on the official `documentation`_ + website. To get started you just need to enable and configure the DBAL: diff --git a/guides/doctrine/migrations/overview.rst b/guides/doctrine/migrations/overview.rst index 01d75694936..0ef8d179f4d 100644 --- a/guides/doctrine/migrations/overview.rst +++ b/guides/doctrine/migrations/overview.rst @@ -9,8 +9,9 @@ layer and offers you the ability to programmatically deploy new versions of your database schema in a safe and standardized way. .. tip:: - You can read more about the Doctrine Database Migrations on the projects - `documentation`_. + + You can read more about the Doctrine Database Migrations on the projects + `documentation`_. All of the migrations functionality is contained in a few console commands: diff --git a/guides/doctrine/mongodb-odm/overview.rst b/guides/doctrine/mongodb-odm/overview.rst index 9554ebf95a6..d479525b9a9 100644 --- a/guides/doctrine/mongodb-odm/overview.rst +++ b/guides/doctrine/mongodb-odm/overview.rst @@ -9,8 +9,9 @@ it works and architecture. You only deal with plain PHP objects and they are persisted transparently without imposing on your domain model. .. tip:: - You can read more about the Doctrine MongoDB Object Document Mapper on the - projects `documentation`_. + + You can read more about the Doctrine MongoDB Object Document Mapper on the + projects `documentation`_. To get started working with Doctrine and the MongoDB Object Document Mapper you just need to enable it: diff --git a/guides/doctrine/orm/overview.rst b/guides/doctrine/orm/overview.rst index abc34197cd6..dccf1cd84a9 100644 --- a/guides/doctrine/orm/overview.rst +++ b/guides/doctrine/orm/overview.rst @@ -9,8 +9,9 @@ powerful DataBase Abstraction Layer (DBAL). It provides transparent persistence for PHP objects. .. tip:: - You can read more about the Doctrine Object Relational Mapper on the - official `documentation`_ website. + + You can read more about the Doctrine Object Relational Mapper on the + official `documentation`_ website. To get started, enable and configure the :doc:`Doctrine DBAL `, then enable the ORM: @@ -61,10 +62,11 @@ any PHP class:: } .. tip:: - When defining your entities, you can omit the getter/setter methods and - let Doctrine create them for you with the ``doctrine:generate:entities`` - command. This only works after you create the mapping information (see - below.) + + When defining your entities, you can omit the getter/setter methods and + let Doctrine create them for you with the ``doctrine:generate:entities`` + command. This only works after you create the mapping information (see + below). To let Doctrine manage your classes (entities in Doctrine2 speak), you need to write mapping information with annotations, XML, or YAML: @@ -128,9 +130,10 @@ write mapping information with annotations, XML, or YAML: .. note:: - If you use YAML or XML to describe your entities, you can omit the creation - of the Entity class, and let the ``doctrine:generate:entities`` command do - it for you. + + If you use YAML or XML to describe your entities, you can omit the creation + of the Entity class, and let the ``doctrine:generate:entities`` command do + it for you. Create the database and the schema related to your metadata information with the following commands: diff --git a/guides/emails.rst b/guides/emails.rst index 786037a2f7b..e10ca06cd4a 100644 --- a/guides/emails.rst +++ b/guides/emails.rst @@ -104,8 +104,9 @@ The mailer is accessible via the ``mailer`` service; from an action:: } .. note:: - To keep things decoupled, the email body has been stored in a template, - rendered with the ``renderView()`` method. + + To keep things decoupled, the email body has been stored in a template, + rendered with the ``renderView()`` method. Using Gmail ----------- diff --git a/guides/event/overview.rst b/guides/event/overview.rst index 01e12d2fcf4..0b21da2dbff 100644 --- a/guides/event/overview.rst +++ b/guides/event/overview.rst @@ -50,9 +50,10 @@ Here are some examples of good event names: * response.filter_content .. note:: - You can of course extend the ``Event`` class to specialize an event further, - or enforce some constraints, but most of the time it adds an unnecessary - level of complexity. + + You can of course extend the ``Event`` class to specialize an event + further, or enforce some constraints, but most of the time it adds an + unnecessary level of complexity. Besides its name, an ``Event`` instance can store additional data about the notified event: @@ -111,11 +112,12 @@ The ``connect()`` method takes two arguments: * A PHP callable to call when the event is notified. .. note:: - A `PHP callable`_ is a PHP variable that can be used by the - ``call_user_func()`` function and returns ``true`` when passed to the - ``is_callable()`` function. It can be a ``\Closure`` instance, a string - representing a function, or an array representing an object method or a - class method. + + A `PHP callable`_ is a PHP variable that can be used by the + ``call_user_func()`` function and returns ``true`` when passed to the + ``is_callable()`` function. It can be a ``\Closure`` instance, a string + representing a function, or an array representing an object method or a + class method. Once a listener is registered with the dispatcher, it waits until the event is notified. For the above example, the dispatcher calls ``$callable`` whenever @@ -123,12 +125,14 @@ the ``user.change_culture`` event is notified; the listener receives an ``Event`` instance as an argument. .. note:: - The listeners are called by the event dispatcher in the same order you - connected them. + + The listeners are called by the event dispatcher in the same order you + connected them. .. tip:: - If you use the Symfony2 MVC framework, listeners are automatically - registered based on your :ref:`configuration `. + + If you use the Symfony2 MVC framework, listeners are automatically + registered based on your :ref:`configuration `. .. index:: single: Event Dispatcher; Notification diff --git a/guides/event/recipes.rst b/guides/event/recipes.rst index 74d423f735a..ccf3b7360ef 100644 --- a/guides/event/recipes.rst +++ b/guides/event/recipes.rst @@ -46,9 +46,10 @@ time. But when you have a long list of dependencies, using setter injection can be the way to go, especially for optional dependencies. .. tip:: - If you use dependency injection like we did in the two examples above, you - can then easily use the Symfony2 Dependency Injection component to elegantly - manage these objects. + + If you use dependency injection like we did in the two examples above, you + can then easily use the Symfony2 Dependency Injection component to + elegantly manage these objects. Doing something before or after a Method Call --------------------------------------------- diff --git a/guides/forms/overview.rst b/guides/forms/overview.rst index 5058384736f..4e5aa384a4e 100644 --- a/guides/forms/overview.rst +++ b/guides/forms/overview.rst @@ -75,9 +75,10 @@ Let's create a simple template to render the form: .. note:: - Form rendering in templates is covered in two dedicated chapters: one for - :doc:`PHP templates `, and one for :doc:`Twig templates - `. + + Form rendering in templates is covered in two dedicated chapters: one for + :doc:`PHP templates `, and one for :doc:`Twig templates + `. When the user submits the form, we also need to handle the submitted data. All the data is stored in a POST parameter with the name of the form:: diff --git a/guides/forms/view.rst b/guides/forms/view.rst index f1e678ff2f6..5c5fc624931 100644 --- a/guides/forms/view.rst +++ b/guides/forms/view.rst @@ -112,13 +112,15 @@ parameter. .. note:: - As you can see, Twig filters are prefixed with "render_". Other than the - methods of the "form" helper, these filters are global and prone to - naming collisions. + + As you can see, Twig filters are prefixed with "render_". Other than the + methods of the "form" helper, these filters are global and prone to + naming collisions. .. tip:: - By default, the ``errors`` helper generates a ``
    `` list, but this - can be easily customized as you will see later in this document. + + By default, the ``errors`` helper generates a ``
      `` list, but this + can be easily customized as you will see later in this document. Last but not the least, a form containing a file input must contain the ``enctype`` attribute; use the ``enctype`` helper to take render it: @@ -170,8 +172,9 @@ The ``render`` helper renders the HTML representation of a field: render($form['title']) ?> .. note:: - The field's template is selected based on the field's class name, as you will - learn later. + + The field's template is selected based on the field's class name, as you will + learn later. The ``label`` helper renders the ``