Merge pull request #35 from thewilkybarkid/doc-tweaks

Doc tweaks

doc/index.rst

@@ -12,9 +12,9 @@ Symfony2Extension provides:
   instance for your contexts
 * Additional ``symfony2`` session for Mink (if ``MinkExtension`` is used)
 
-Symfony2Extension is here to replace obsolete BehatBundle. To migrate
+Symfony2Extension is here to replace the obsolete BehatBundle. To migrate
 your Behat 2.3 + Symfony2 feature suite,
-`read migration guide </symfony2/migrating_from_2.3_to_2.4.html>`_.
+`read the migration guide </symfony2/migrating_from_2.3_to_2.4.html>`_.
 
 Installation
 ------------
@@ -127,11 +127,11 @@ The easiest way to keep your suite updated is to use `Composer <http://getcompos
 Usage
 -----
 
-After installing extension, there would be 2 usage options available for you:
+After installing the extension, there are 2 usage options available:
 
-1. If you're on the php 5.4+, you can simply use 
+1. If you're using PHP 5.4+, you can simply use the
    ``Behat\Symfony2Extension\Context\KernelDictionary`` trait inside your
-   ``FeatureContext`` or any of its subcontexts. This trait will provide
+   ``FeatureContext`` or any of its subcontexts. This trait will provide the
    ``getKernel()`` and ``getContainer()`` methods for you.
 
 2. Implementing ``Behat\Symfony2Extension\Context\KernelAwareInterface`` with
@@ -140,13 +140,13 @@ After installing extension, there would be 2 usage options available for you:
    parent contexts from subcontexts when the only thing you need is a kernel instance.
 
 There's a common thing between those 2 methods. In each of those, target context
-will implement ``setKernel(KernelInterface $kernel)`` method. This method would be
+will implement the ``setKernel(KernelInterface $kernel)`` method. This method would be
 automatically called **immediately after** each context creation before each scenario.
 After context constructor, but before any instance hook or definition call.
 
 .. note::
 
-    Application kernel will be automatically rebooted between scenarios, so your
+    The application kernel will be automatically rebooted between scenarios, so your
     scenarios would have almost absolutely isolated state.
 
 Initialize Bundle Suite
@@ -156,11 +156,11 @@ In order to start with your feature suite for specific bundle, execute:
 
 .. code-block:: bash
 
-    $ php behat.phar --init "@YouBundleName"
+    $ php behat.phar --init "@YourBundleName"
 
 .. note::
 
-    Extension provides alternative ways to specify bundle:
+    The extension provides an alternative way to specify the bundle:
 
     .. code-block:: bash
 
@@ -169,23 +169,23 @@ In order to start with your feature suite for specific bundle, execute:
 Run Bundle Suite
 ~~~~~~~~~~~~~~~~
 
-In order to run feature suite of specific bundle, execute:
+In order to run the feature suite for a specific bundle, execute:
 
 .. code-block:: bash
 
-    $ php behat.phar "@YouBundleName"
+    $ php behat.phar "@YourBundleName"
 
 .. note::
 
-    Extension provides alternative ways to specify bundle or even
+    The extension provides alternative ways to specify the bundle, or even
     single feature inside it:
 
     .. code-block:: bash
 
-        $ php behat.phar "@YouBundleName/registration.feature"
+        $ php behat.phar "@YourBundleName/registration.feature"
         $ php behat.phar src/YourCompany/YourBundleName/Features/registration.feature
 
-If you run specific bundle suite quite often, it might be useful to
+If you regularly run the specific bundle suite, it might be useful to
 use Behat profile for that:
 
 .. code-block:: yaml
@@ -202,13 +202,13 @@ use Behat profile for that:
             Behat\Symfony2Extension\Extension:
                 bundle: GroupBundle
 
-Now if you need to run ``UserBundle`` feature suite, you could just execute:
+Now if you need to run the ``UserBundle`` feature suite, you could just execute:
 
 .. code-block:: bash
 
     $ php behat.phar -p=user
 
-Notice that in this case, you also can avoid bundlename specification for single
+Notice that in this case, you also can avoid bundlename specification for a single
 feature run:
 
 .. code-block:: bash
@@ -247,7 +247,7 @@ Now just enable ``mink_driver`` in Symfony2Extension:
                  mink_driver: true
              mink_extension.phar: ~
 
-Also, you can make ``symfony2`` session the default one by setting ``default_session``
+Also, you can make the ``symfony2`` session the default one by setting ``default_session``
 option in MinkExtension:
 
 .. code-block:: yaml
@@ -260,7 +260,7 @@ option in MinkExtension:
             mink_extension.phar:
                 default_session: 'symfony2'
                 
-If you have installed via Composer, your ``behat.yml`` would instead look something like the below:
+If you installed via Composer, your ``behat.yml`` would instead look something like the below:
 
 .. code-block:: yaml
 
@@ -275,9 +275,9 @@ If you have installed via Composer, your ``behat.yml`` would instead look someth
 Application Level Feature Suite
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You are not forced to use bundle-centric structure for your feature suites.
+You are not forced to use a bundle-centric structure for your feature suites.
 If you want to keep your suite application level, you can simply do it by specifying
-proper ``features`` path and ``context.class`` in your ``behat.yml``:
+a proper ``features`` path and ``context.class`` in your ``behat.yml``:
 
 .. code-block:: yaml
 
@@ -289,8 +289,8 @@ proper ``features`` path and ``context.class`` in your ``behat.yml``:
 
 .. note::
 
-    Keep in mind, that ``Symfony2Extension`` relies on ``Symfony2`` autoloader for
-    context discover and disables Behat bundled autoloader (aka ``bootstrap`` folder).
+    Keep in mind, that ``Symfony2Extension`` relies on the ``Symfony2`` autoloader for
+    context discovery and disables the Behat-bundled autoloader (aka ``bootstrap`` folder).
     So make sure that your context class is discoverable by ``Symfony2`` autoloader
     (place it in proper folder/namespace).
 
@@ -299,50 +299,49 @@ proper ``features`` path and ``context.class`` in your ``behat.yml``:
     If you're using both ``Symfony2Extension`` and ``MinkExtension`` and have defined
     wrong classname for your context class, you can run into problem where suite
     will still be runnable, but some of your custom definitions/hooks/methods will
-    not be available. This happens because ``Behat`` uses bundled with ``MinkExtension``
+    not be available. This happens because ``Behat`` uses the ``MinkExtension``-bundled
     context class instead.
 
-    So here's what's happening:
+    Here's what's happening:
 
     1. Behat tries to check existence of FeatureContext class (default) with
        `PredefinedClassGuesser <https://github.com/Behat/Behat/blob/master/src/Behat/Behat/Context/ClassGuesser/PredefinedClassGuesser.php>`_
        and obviously can't.
-    2. Behat `tries another guessers <https://github.com/Behat/Behat/blob/master/src/Behat/Behat/Context/ContextDispatcher.php#L62-66>`_
+    2. Behat `tries other guessers <https://github.com/Behat/Behat/blob/master/src/Behat/Behat/Context/ContextDispatcher.php#L62-66>`_
        with lower priorities.
     3. `There is one
        <https://github.com/Behat/MinkExtension/blob/master/src/Behat/MinkExtension/Context/ClassGuesser/MinkContextClassGuesser.php#L20>`_
        defined by ``MinkExtension``, which gets matched and tells Behat to use
        ``Behat\MinkExtension\Context\MinkContext`` as main context class.
 
-    So, your ``FeatureContext`` isn't used really. ``Behat\MinkExtension\Context\MinkContext``
+    So, your ``FeatureContext`` isn't used, and ``Behat\MinkExtension\Context\MinkContext`` is
     used instead.
 
-    So be sure to check that your suite is runned in proper context (by looking at
-    paths next to steps) and that you've defined proper, discoverable context classname.
+    Be sure to check that your suite is run in a proper context (by looking at
+    paths next to steps) and that you've defined proper, discoverable context classnames.
 
 Configuration
 -------------
 
-Symfony2Extension comes with flexible configuration system, that gives you ability to
+Symfony2Extension comes with a flexible configuration system, that gives you the ability to
 configure Symfony2 kernel inside Behat to fulfil all your needs.
 
-* ``bundle`` - specifies bundle to be runned for specific profile
-* ``kernel`` - specifies options to instantiate kernel:
+* ``bundle`` - specifies a bundle to be run for specific profile
+* ``kernel`` - specifies options to instantiate the kernel:
 
-  - ``bootstrap`` - defines autoloading/bootstraping file to autoload
-    all the needed classes in order to instantiate kernel.
-  - ``path`` - defines path to the kernel class to be requires in order
-    to instantiate it.
-  - ``class`` - defines name of the kernel class.
-  - ``env`` - defines environment in which kernel should be instantiated and used
+  - ``bootstrap`` - defines an autoloading/bootstraping file to autoload
+    all the required classes to instantiate the kernel.
+  - ``path`` - defines the path to the kernel class in order to instantiate it.
+  - ``class`` - defines the name of the kernel class.
+  - ``env`` - defines the environment in which kernel should be instantiated and used
     inside suite.
   - ``debug`` - defines whether kernel should be instantiated with ``debug`` option
     set to true.
 
-* ``context`` - specifies options, used to guess context class:
+* ``context`` - specifies options, used to guess the context class:
 
   - ``path_suffix`` - suffix from bundle directory for features.
   - ``class_suffix`` - suffix from bundle classname for context class.
 
-* ``mink_driver`` - if set to true - extension will load ``symfony2`` session
+* ``mink_driver`` - if set to true - extension will load the ``symfony2`` session
   for Mink.