Docs re-org and removal of small sections

Author: weaverryan

_build/redirection_map

@@ -76,13 +76,20 @@
 /book/configuration /configuration
 /book/propel /propel/propel
 /book/performance /performance
-/cookbook/assetic/apply_to_option /assetic/apply_to_option
-/cookbook/assetic/asset_management /assetic/asset_management
-/cookbook/assetic/index /assetic
-/cookbook/assetic/jpeg_optimize /assetic/jpeg_optimize
-/cookbook/assetic/php /assetic/php
-/cookbook/assetic/uglifyjs /assetic/uglifyjs
-/cookbook/assetic/yuicompressor /assetic/yuicompressor
+/cookbook/assetic/apply_to_option /frontend/assetic/apply_to_option
+/cookbook/assetic/asset_management /frontend/assetic/asset_management
+/cookbook/assetic/index /frontend/assetic
+/cookbook/assetic/jpeg_optimize /frontend/assetic/jpeg_optimize
+/cookbook/assetic/php /frontend/assetic/php
+/cookbook/assetic/uglifyjs /frontend/assetic/uglifyjs
+/cookbook/assetic/yuicompressor /frontend/assetic/yuicompressor
+/assetic /frontend/assetic
+/assetic/apply_to_option /frontend/assetic/apply_to_option
+/assetic/asset_management /frontend/assetic/asset_management
+/assetic/jpeg_optimize /frontend/assetic/jpeg_optimize
+/assetic/php /frontend/assetic/php
+/assetic/uglifyjs /frontend/assetic/uglifyjs
+/assetic/yuicompressor /frontend/assetic/yuicompressor
 /cookbook/bundles/best_practices /bundles/best_practices
 /cookbook/bundles/configuration /bundles/configuration
 /cookbook/bundles/extension /bundles/extension
@@ -150,7 +157,8 @@
 /cookbook/event_dispatcher/event_listener /event_dispatcher
 /cookbook/event_dispatcher/index /event_dispatcher
 /cookbook/event_dispatcher/method_behavior /event_dispatcher/method_behavior
-/cookbook/expressions /expressions/expressions
+/cookbook/expressions /security/expressions
+/expressions /security/expressions
 /cookbook/form/create_custom_field_type /form/create_custom_field_type
 /cookbook/form/create_form_type_extension /form/create_form_type_extension
 /cookbook/form/data_transformers /form/data_transformers
@@ -181,10 +189,10 @@
 /cookbook/profiler/matchers /profiler/matchers
 /cookbook/profiler/profiling_data /profiler/profiling_data
 /cookbook/profiler/storage /profiler/storage
-/cookbook/psr7 /request/psr7
+/cookbook/psr7 /components/psr7
 /cookbook/request/index /request
-/cookbook/request/load_balancer_reverse_proxy /request/load_balancer_reverse_proxy
-/cookbook/request/mime_type /request/mime_type
+/cookbook/request/load_balancer_reverse_proxy /deployment/proxies
+/cookbook/request/mime_type /reference/configuration/framework#formats
 /cookbook/routing/conditions /routing/conditions
 /cookbook/routing/custom_route_loader /routing/custom_route_loader
 /cookbook/routing/debug /routing/debug
@@ -303,6 +311,7 @@
 /components/form/type_guesser /form/type_guesser
 /components/http_foundation/index /components/http_foundation
 /components/http_foundation/introduction /components/http_foundation
+/components/http_foundation/trusting_proxies /deployment/proxies
 /components/http_kernel/introduction /components/http_kernel
 /components/http_kernel/index /components/http_kernel
 /components/property_access/introduction /components/property_access
@@ -327,3 +336,4 @@
 /form /forms
 /testing/simulating_authentication /testing/http_authentication
 /validation/group_service_resolver /form/validation_group_service_resolver
+/request/load_balancer_reverse_proxy /deployment/proxies

best_practices/web-assets.rst

@@ -49,7 +49,7 @@ tools like GruntJS.
     Use Assetic to compile, combine and minimize web assets, unless you're
     comfortable with frontend tools like GruntJS.
 
-:doc:`Assetic </assetic/asset_management>` is an asset manager capable
+:doc:`Assetic </frontend/assetic/asset_management>` is an asset manager capable
 of compiling assets developed with a lot of different frontend technologies
 like LESS, Sass and CoffeeScript. Combining all your assets with Assetic is a
 matter of wrapping all the assets with a single Twig tag:
@@ -87,8 +87,8 @@ Learn More about Assetic
 ------------------------
 
 Assetic can also minimize CSS and JavaScript assets
-:doc:`using UglifyCSS/UglifyJS </assetic/uglifyjs>` to speed up your
-websites. You can even :doc:`compress images </assetic/jpeg_optimize>`
+:doc:`using UglifyCSS/UglifyJS </frontend/assetic/uglifyjs>` to speed up your
+websites. You can even :doc:`compress images </frontend/assetic/jpeg_optimize>`
 with Assetic to reduce their size before serving them to the user. Check out
 the `official Assetic documentation`_ to learn more about all the available
 features.

bundles/best_practices.rst

@@ -31,7 +31,7 @@ Bundle Name
 A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or
 `PSR-4`_ interoperability standards for PHP namespaces and class names: it starts
 with a vendor segment, followed by zero or more category segments, and it ends
-with the namespace short name, which must end with a ``Bundle`` suffix.
+with the namespace short name, which must end with ``Bundle``.
 
 A namespace becomes a bundle as soon as you add a bundle class to it. The
 bundle class name must follow these simple rules:
@@ -48,8 +48,8 @@ Here are some valid bundle namespaces and class names:
 ==========================  ==================
 Namespace                   Bundle Class Name
 ==========================  ==================
-``Acme\Bundle\BlogBundle``  ``AcmeBlogBundle``
-``Acme\BlogBundle``         ``AcmeBlogBundle``
+``Acme\Bundle\BlogBundle``  AcmeBlogBundle
+``Acme\BlogBundle``         AcmeBlogBundle
 ==========================  ==================
 
 By convention, the ``getName()`` method of the bundle class should return the
@@ -58,8 +58,7 @@ class name.
 .. note::
 
     If you share your bundle publicly, you must use the bundle class name as
-    the name of the repository (``AcmeBlogBundle`` and not ``BlogBundle``
-    for instance).
+    the name of the repository (AcmeBlogBundle and not BlogBundle for instance).
 
 .. note::
 
@@ -68,7 +67,7 @@ class name.
     :class:`Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle`.
 
 Each bundle has an alias, which is the lower-cased short version of the bundle
-name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias
+name using underscores (``acme_blog`` for AcmeBlogBundle). This alias
 is used to enforce uniqueness within a project and for defining bundle's
 configuration options (see below for some usage examples).
 
@@ -105,8 +104,8 @@ that automated tools can rely on:
   bundles are published under the MIT license, but you can `choose any license`_;
 * ``Resources/doc/index.rst``: The root file for the Bundle documentation.
 
-The depth of sub-directories should be kept to the minimum for most used
-classes and files (two levels maximum).
+The depth of subdirectories should be kept to a minimum for the most used
+classes and files. Two levels is the maximum.
 
 The bundle directory is read-only. If you need to write temporary files, store
 them under the ``cache/`` or ``log/`` directory of the host application. Tools
@@ -138,9 +137,9 @@ Classes
 -------
 
 The bundle directory structure is used as the namespace hierarchy. For
-instance, a ``ContentController`` controller is stored in
-``Acme/BlogBundle/Controller/ContentController.php`` and the fully qualified
-class name is ``Acme\BlogBundle\Controller\ContentController``.
+instance, a ``ContentController`` controller which is stored in
+``Acme/BlogBundle/Controller/ContentController.php`` would have the fully
+qualified class name of ``Acme\BlogBundle\Controller\ContentController``.
 
 All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
 
@@ -158,8 +157,8 @@ Vendors
 A bundle must not embed third-party PHP libraries. It should rely on the
 standard Symfony autoloading instead.
 
-A bundle should not embed third-party libraries written in JavaScript, CSS or
-any other language.
+A bundle should also not embed third-party libraries written in JavaScript,
+CSS or any other language.
 
 Tests
 -----
@@ -183,10 +182,13 @@ Documentation
 
 All classes and functions must come with full PHPDoc.
 
-Extensive documentation should also be provided in the
-:doc:`reStructuredText </contributing/documentation/format>` format, under
-the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is
-the only mandatory file and must be the entry point for the documentation.
+Extensive documentation should also be provided in the ``Resources/doc/`` 
+directory.
+The index file (for example ``Resources/doc/index.rst`` or 
+``Resources/doc/index.md``) is the only mandatory file and must be the entry 
+point for the documentation. The 
+:doc:`reStructuredText (rST) </contributing/documentation/format>` is the format
+used to render the documentation on symfony.com.
 
 Installation Instructions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -232,7 +234,6 @@ following standardized instructions in your ``README.md`` file.
             {
                 $bundles = array(
                     // ...
-
                     new <vendor>\<bundle-name>\<bundle-long-name>(),
                 );
 
@@ -399,9 +400,9 @@ The ``composer.json`` file should include at least the following metadata:
 ``name``
     Consists of the vendor and the short bundle name. If you are releasing the
     bundle on your own instead of on behalf of a company, use your personal name
-    (e.g. ``johnsmith/blog-bundle``). The bundle short name excludes the vendor
-    name and separates each word with an hyphen. For example: ``AcmeBlogBundle``
-    is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is
+    (e.g. ``johnsmith/blog-bundle``). Exclude the vendor name from the bundle
+    short name and separate each word with an hyphen. For example: AcmeBlogBundle
+    is transformed into ``blog-bundle`` and AcmeSocialConnectBundle is
     transformed into ``social-connect-bundle``.
 
 ``description``
@@ -411,8 +412,7 @@ The ``composer.json`` file should include at least the following metadata:
     Use the ``symfony-bundle`` value.
 
 ``license``
-    ``MIT`` is the preferred license for Symfony bundles, but you can use any
-    other license.
+    a string (or array of strings) with a `valid license identifier`_, such as ``MIT``.
 
 ``autoload``
     This information is used by Symfony to load the classes of the bundle. The
@@ -497,3 +497,4 @@ Learn more
 .. _`Semantic Versioning Standard`: http://semver.org/
 .. _`Packagist`: https://packagist.org/
 .. _`choose any license`: http://choosealicense.com/
+.. _`valid license identifier`: https://spdx.org/licenses/

components/expression_language.rst

@@ -119,7 +119,6 @@ Learn More
     :maxdepth: 1
     :glob:
 
-    /expressions
     /components/expression_language/*
     /service_container/expression_language
     /reference/constraints/Expression

components/filesystem.rst

@@ -79,12 +79,13 @@ exists
 ~~~~~~
 
 :method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the
-presence of all files or directories and returns ``false`` if a file is missing::
+presence of one or more files or directories and returns ``false`` if any of
+them is missing::
 
     // this directory exists, return true
     $fs->exists('/tmp/photos');
 
-    // rabbit.jpg exists, bottle.png does not exists, return false
+    // rabbit.jpg exists, bottle.png does not exist, return false
     $fs->exists(array('rabbit.jpg', 'bottle.png'));
 
 .. note::
@@ -95,10 +96,11 @@ presence of all files or directories and returns ``false`` if a file is missing:
 copy
 ~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` is used to copy
-files. If the target already exists, the file is copied only if the source
-modification date is later than the target. This behavior can be overridden by
-the third boolean argument::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` makes a copy of a
+single file (use :method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` to
+copy directories). If the target already exists, the file is copied only if the
+source modification date is later than the target. This behavior can be overridden
+by the third boolean argument::
 
     // works only if image-ICC has been modified after image.jpg
     $fs->copy('image-ICC.jpg', 'image.jpg');
@@ -128,8 +130,8 @@ your own with the second argument. The third argument is the access time::
 chown
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` is used to change
-the owner of a file. The third argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` changes the owner of
+a file. The third argument is a boolean recursive option::
 
     // set the owner of the lolcat video to www-data
     $fs->chown('lolcat.mp4', 'www-data');
@@ -144,8 +146,8 @@ the owner of a file. The third argument is a boolean recursive option::
 chgrp
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` is used to change
-the group of a file. The third argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` changes the group of
+a file. The third argument is a boolean recursive option::
 
     // set the group of the lolcat video to nginx
     $fs->chgrp('lolcat.mp4', 'nginx');
@@ -160,8 +162,8 @@ the group of a file. The third argument is a boolean recursive option::
 chmod
 ~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` is used to change
-the mode of a file. The fourth argument is a boolean recursive option::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` changes the mode or
+permissions of a file. The fourth argument is a boolean recursive option::
 
     // set the mode of the video to 0600
     $fs->chmod('video.ogg', 0600);
@@ -176,8 +178,8 @@ the mode of a file. The fourth argument is a boolean recursive option::
 remove
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` is used to remove
-files, symlinks, directories easily::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` deletes files,
+directories and symlinks::
 
     $fs->remove(array('symlink', '/path/to/directory', 'activity.log'));
 
@@ -189,8 +191,8 @@ files, symlinks, directories easily::
 rename
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` is used to rename
-files and directories::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` changes the name
+of a single file or directory::
 
     // rename a file
     $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
@@ -213,8 +215,8 @@ support symbolic links, a third boolean argument is available::
 makePathRelative
 ~~~~~~~~~~~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` returns
-the relative path of a directory given another one::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` takes two
+absolute paths and returns the relative path from the second path to the first one::
 
     // returns '../'
     $fs->makePathRelative(
@@ -227,8 +229,10 @@ the relative path of a directory given another one::
 mirror
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` mirrors a
-directory::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` copies all the
+contents of the source directory into the target one (use the
+:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` method to copy single
+files)::
 
     $fs->mirror('/path/to/source', '/path/to/target');
 
@@ -253,8 +257,8 @@ dumpFile
 .. versionadded:: 2.3
     The ``dumpFile()`` was introduced in Symfony 2.3.
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` allows you to
-dump contents to a file. It does this in an atomic manner: it writes a temporary
+:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` saves the given
+contents into a file. It does this in an atomic manner: it writes a temporary
 file first and then moves it to the new file location when it's finished.
 This means that the user will always see either the complete old file or
 complete new file (but never a partially-written file)::

components/finder.rst

@@ -55,6 +55,12 @@ the Finder instance.
     :phpfunction:`iterator_to_array` method, or get the number of items with
     :phpfunction:`iterator_count`.
 
+.. caution::
+
+    The ``Finder`` object doesn't reset its internal state automatically.
+    This means that you need to create a new instance if you do not want
+    get mixed results.
+
 .. caution::
 
     When searching through multiple locations passed to the
@@ -83,7 +89,7 @@ Search in several locations by chaining calls to
 :method:`Symfony\\Component\\Finder\\Finder::in`::
 
     // search inside *both* directories
-    $finder->files()->in(array(__DIR__, '/elsewhere'));
+    $finder->in(array(__DIR__, '/elsewhere'));
 
     // same as above
     $finder->in(__DIR__)->in('/elsewhere');

components/http_foundation.rst

@@ -356,9 +356,9 @@ UTF-8.
 Sending the Response
 ~~~~~~~~~~~~~~~~~~~~
 
-Before sending the Response, you can ensure that it is compliant with the HTTP
-specification by calling the
-:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method::
+Before sending the Response, you can optionally call the
+:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method to fix any
+incompatibility with the HTTP specification (e.g. a wrong ``Content-Type`` header)::
 
     $response->prepare($request);
 
@@ -611,7 +611,6 @@ Learn More
     /components/http_foundation/*
     /controller
     /controller/*
-    /request/*
     /session/*
     /http_cache/*
 

components/http_foundation/trusting_proxies.rst

@@ -7,7 +7,7 @@ Trusting Proxies
 .. tip::
 
     If you're using the Symfony Framework, start by reading
-    :doc:`/request/load_balancer_reverse_proxy`.
+    :doc:`/deployment/proxies`.
 
 If you find yourself behind some sort of proxy - like a load balancer - then
 certain header information may be sent to you using special ``X-Forwarded-*``