Improve the docs (#77)

Add more information about the bundle's behaviour after #76

Author: bocharsky-bw

doc/index.rst

@@ -4,7 +4,8 @@ Sass For Symfony!
 This bundle makes it easy to use Sass with Symfony's AssetMapper Component
 (no Node required!).
 
-- Automatically downloads the correct Sass binary
+- Automatically detects the Sass binary installed in the system
+- Automatically downloads the correct Sass binary if it's not detected in the system
 - Adds a ``sass:build`` command to build and watch your Sass changes
 
 .. tip::
@@ -25,7 +26,7 @@ Install the bundle:
 Usage
 -----
 
-Start by writing your first Sass file ``assets/styles/app.scss``, and let's add some basic style
+Start by writing your first Sass file ``assets/styles/app.scss``, and let's add some basic style:
 
 .. code-block:: scss
 
@@ -37,7 +38,7 @@ Start by writing your first Sass file ``assets/styles/app.scss``, and let's add
       background: $red;
     }
 
-Then point your styles in your template
+Then point your styles in your template:
 
 .. code-block:: html+twig
 
@@ -79,16 +80,21 @@ to be started whenever you run ``symfony server:start``:
 How Does it Work?
 -----------------
 
-The first time you run one of the Sass commands, the bundle will download the correct Sass binary for your system into the ``bin/dart-sass`` directory.
+The first time you run one of the Sass commands, the bundle will automatically try to detect
+the correct Sass binary installed in the system and use it. If the binary is not found,
+the bundle will automatically download the correct one for your system and put it into
+the ``bin/dart-sass`` directory.
 
-When you run ``sass:build``, that binary is used to compile Sass files into a ``var/sass/app.built.css`` file. Finally, when the contents of ``assets/styles/app.scss`` are requested, the bundle swaps the contents of that file with the contents of ``var/sass/app.built.css``. Nice!
+When you run ``sass:build``, that binary is used to compile Sass files into a ``var/sass/app.built.css``
+file. Finally, when the contents of ``assets/styles/app.scss`` are requested, the bundle swaps
+the contents of that file with the contents of ``var/sass/app.built.css``. Nice!
 
 Excluding Sass Files from AssetMapper
 -------------------------------------
 
 Because you have ``.scss`` files in your ``assets/`` directory, when you deploy, these
 source files will be copied into the ``public/assets/`` directory. To prevent that,
-you can exclude them from asset mapper:
+you can exclude them from AssetMapper:
 
 .. code-block:: yaml
     # config/packages/asset_mapper.yaml
@@ -106,19 +112,20 @@ you can exclude them from asset mapper:
     this *is* used in AssetMapper and its contents are swapped for the final, built CSS.
 
 
-How to Get Source Sass Files for 3rd-party Libraries
+How to Get Source Sass Files for 3rd-Party Libraries
 ----------------------------------------------------
 
-The easiest way to get 3rd-party Sass files is via Composer. For example, see
-the section below to know how to get the source Sass files for Bootstrap.
+The easiest way to get 3rd-party Sass files is via `Composer <https://getcomposer.org/>`_. For example, see
+the section below to know how to get the source Sass files for `Bootstrap <https://getbootstrap.com/>`_.
 
 But if you're using a library that isn't available via Composer, you’ll need
 to either download it to your app manually or grab it via NPM.
 
 Using Bootstrap Sass
 ~~~~~~~~~~~~~~~~~~~~
 
-`Bootstrap <https://getbootstrap.com/>`_ is available as Sass, allowing you to customize the look and feel of your app. An easy way to get the source Sass files is via a Composer package:
+`Bootstrap <https://getbootstrap.com/>`_ is available as Sass, allowing you to customize
+the look and feel of your app. An easy way to get the source Sass files is via a Composer package:
 
 .. code-block:: terminal
 
@@ -169,7 +176,8 @@ When you deploy, run ``sass:build`` command before the ``asset-map:compile`` com
 Limitation: ``url()`` Relative Paths
 ------------------------------------
 
-When using ``url()`` inside a Sass file, currently, the path must be relative to the *root* ``.scss`` file. For example, suppose the root ``.scss`` file is:
+When using ``url()`` inside a Sass file, currently, the path must be relative to the *root* ``.scss`` file.
+For example, suppose the root ``.scss`` file is:
 
 .. code-block:: scss
 
@@ -189,7 +197,8 @@ Assume there is an ``assets/images/login-bg.png`` file that you want to refer to
         background-image: url('../images/login-bg.png');
     }
 
-It should be possible to use ``url()`` with a path relative to the current file. However, that is not currently possible. See `this issue <https://github.com/SymfonyCasts/sass-bundle/issues/2>`_ for more details.
+It should be possible to use ``url()`` with a path relative to the current file. However, that is not
+currently possible. See `this issue <https://github.com/SymfonyCasts/sass-bundle/issues/2>`_ for more details.
 
 Configuration
 -------------
@@ -204,13 +213,14 @@ To see the full config from this bundle, run:
 Source Sass file
 ~~~~~~~~~~~~~~~~
 
-The main option is ``root_sass`` option, which defaults to ``assets/styles/app.scss``. This represents the source Sass file.
+The main option is the ``root_sass`` option, which defaults to ``assets/styles/app.scss``.
+This represents the source Sass file:
 
 .. code-block:: yaml
 
     # config/packages/symfonycasts_sass.yaml
     symfonycasts_sass:
-        root_sass:  'assets/styles/app.scss'
+        root_sass: 'assets/styles/app.scss'
 
 .. note::
 
@@ -241,7 +251,7 @@ You can configure most of the `Dart Sass CLI options <https://sass-lang.com/docu
             # Register additional load paths. Defaults to empty array.
             # load_path: []
 
-            # Wether to generate source maps. Defaults to true when "kernel.debug" is true.
+            # Whether to generate source maps. Defaults to true when "kernel.debug" is true.
             # source_map: true
 
             # Embed source file contents in source maps. Defaults to false.
@@ -266,13 +276,23 @@ You can configure most of the `Dart Sass CLI options <https://sass-lang.com/docu
 Using a different binary
 ------------------------
 
-This bundle already installed for you the right binary. However, if you already have a binary installed on your machine you can instruct the bundle to use that binary, set the ``binary`` option:
+This bundle has already detected or installed for you the right binary. However, if you already have a binary
+installed on your machine and somehow the bundle has not been able to find it automatically - you can instruct
+the bundle to use that binary, set the ``binary`` option:
 
 .. code-block:: yaml
 
     symfonycasts_sass:
         binary: 'node_modules/.bin/sass'
 
+.. tip::
+
+    If a path in the ``binary`` option is explicitly specified - the bundle will just use it
+    which means it will not try to search a binary itself or download it automatically for your system.
+    To let the bundle take care of it automatically - do not specify the ``binary`` option.
+
+
+
 Register Additional Load Paths
 ------------------------------