finishing docs

Author: weaverryan

docs/bootstrap.rst

@@ -1,19 +1,116 @@
 Using Bootstrap CSS & JS
 ========================
 
-TODO - show how to bring in bootstrap JS and bootstrap-sass.
+Want to use Bootstrap (or something similar) in your project? No problem!
+First, install it. To be able to customize things further, we'll install
+``bootstrap-sass``:
 
-Here is an example from before to include... because I think it's really nice :).
+.. code-block:: terminal
 
-    // when no file path is defined (i.e. no file extension) Webpack loads the
-    // given JavaScript module installed in node_modules/ dir (Webpack knows all
-    // the specific files that must be loaded and in which order)
-    require('bootstrap-star-rating');
+    $ yarn add bootstrap-sass --dev
+
+Importing Bootstrap SASS
+------------------------
+
+Now that ``bootstrap-sass`` lives in your ``node_modules`` directory, you can
+import it from any SASS or JavaScript file. For example, if you're already have
+a ``global.scss`` file, import it from there:
+
+.. code-block:: css
+
+    // assets/css/global.scss
+
+    // customize some Bootstrap variables
+    $brand-primary:         darken(#428bca, 20%);
+
+    // the ~ allows you to reference things in node_modules
+    @import '~bootstrap-sass/assets/stylesheets/bootstrap';
+
+That's it! This imports the ``node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss``
+file into ``global.scss``. You can even customize the Bootstrap variables first!
+
+.. tip::
+
+    If you don't need *all* of Bootstrap's features, you can include specific files
+    in the ``bootstrap`` directory instead - e.g. ``~bootstrap-sass/assets/stylesheets/bootstrap/alerts``.
+
+After including ``bootstrap-sass``, your webpack builds might become slow. To fix
+this, you can use the ``resolve_url_loader`` option:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+    +     enableSassLoader({
+    +         'resolve_url_loader' => false
+    +     })
+    ;
+
+This disables the ``resolve-url-loader`` in Webpack, which means that any
+``url()`` paths in your SASS files must now be relative to the original source
+entry file instead of whatever file you're inside of (see `Problems with url()`_).
+To load Bootstrap, you'll need to override the path to its icons:
+
+.. code-block:: diff
+
+    // assets/css/global.scss
+
+    + $icon-font-path: "~bootstrap-sass/assets/fonts/bootstrap/";
+
+    + // set if you're also including font-awesome
+    + // $fa-font-path: "~font-awesome/fonts";
 
-    // when a file path is given, but it doesn't start with '/' or './', the file
-    // path is considered relative to node_modules/ dir
+    @import '~bootstrap-sass/assets/stylesheets/bootstrap';
+
+Importing Bootstrap JavaScript
+------------------------------
+
+Bootstrap JavaScript requires jQuery, so make sure you have this installed:
+
+.. code-block:: terminal
+
+    $ yarn add jquery --dev
+
+Next, make sure call ``.autoProvidejQuery()`` in your ``webpack.config.js`` file:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+    +     .autoProvidejQuery()
+
+This is needed because Bootstrap expects jQuery to be available as a global
+variable. Now, require bootstrap from any of your JavaScript files:
+
+.. code-block:: javascript
+
+    // main.js
+
+    var $ = require('jquery');
+    // JS is equivalent to the normal "bootstrap" package
+    // no need to set this to a variable, just require it
+    require('bootstrap-sass');
+
+    // or you can include specific pieces
+    // require('bootstrap-sass/javascripts/bootstrap/tooltip');
+    // require('bootstrap-sass/javascripts/bootstrap/popover');
+
+    $(document).ready(function() {
+        $('[data-toggle="popover"]').popover();
+    });
+
+Thanks to ``autoProvidejQuery()``, you can require any other jQuery
+plugins in a similar way:
+
+.. code-block:: javascript
+
+    // ...
+
+    // require the JavaScript
+    require('bootstrap-star-rating');
+    // require 2 CSS files needed
     require('bootstrap-star-rating/css/star-rating.css');
+    require('bootstrap-star-rating/themes/krajee-svg/theme.css');
 
-    // when a file path is given and it starts with '/', './', or '../', it's considered
-    // as the full file path for the asset (it can live outside the node_modules/ dir)
-    require('../../../../../node_modules/bootstrap-star-rating/themes/krajee-svg/theme.css');
+.. _`Problems with url()`: https://github.com/webpack-contrib/sass-loader#problems-with-url

docs/page-specific-assets.rst

@@ -1,4 +1,45 @@
 Creating Page-Specific CSS/JS
 =============================
 
-TODO
+If you're creating a single page app (SPA), then you probably only need to define
+*one* entry in ``webpack.config.js``. But if you have multiple pages, you might
+want page-specific CSS and JavaScript.
+
+For example, suppose you have a checkout page that has its own JavaScript. Create
+a new ``checkout`` entry:
+
+.. code-block:: diff
+
+    // webpack.config.js
+
+    Encore
+        // an existing entry
+        .addEntry('app', './assets/js/main.js')
+        // a global styles entry
+        .addStyleEntry('global', './assets/css/global.scss')
+
+    +     .addEntry('checkout', './assets/js/checkout.js')
+    ;
+
+Inside ``checkout.js``, add or require the JavaScript and CSS you need.
+Then, just include a ``script`` tag for ``checkout.js`` on the checkout
+page (and a ``link`` tag for ``checkout.css`` if you import any CSS).
+
+Multiple Entries Per Page?
+--------------------------
+
+Typically, you should include only *one* entry JavaScript per page. This means
+the checkout page will include ``checkout.js``, but will *not* include the
+``app.js`` that's used on the other pages. Think of the checkout page as its
+own "app", where ``checkout.js`` includes all the functionality you need.
+
+However, if there is some global JavaScript that you want included on *every*
+page, you *can* create an entry that contains that code and include both that
+entry *and* your page-specific entry. For example, suppose that the ``app``
+entry above contains JavaScript you want on every page. In that case, include
+both ``app.js`` and ``checkout.js`` on the checkout page.
+
+.. tip::
+
+    Be sure to create a :doc:`shared entry </shared-entry>` to avoid duplicating
+    the Webpack bootstrap logic and any shared modules.

docs/shared-entry.rst

@@ -1,5 +1,5 @@
-Creating a Shared Entry
-=======================
+Creating a Shared Commons Entry
+===============================
 
 Suppose you have multiple entry files and *each* requires ``jquery``. In this
 case, *each* output file will contain jQuery, slowing down your user's experience.

docs/simple-example.rst

@@ -159,4 +159,9 @@ In this case, ``main.js`` is being added to an entry called ``app`` in ``webpack
 
 As soon as you require a CSS file, both an ``app.js`` **and** an ``app.css`` file
 will be created. You'll need to add a link tag to the ``app.css`` file in your
-templates.
+templates:
+
+.. code-block:: diff
+
+    <link rel="stylesheet" href="{{ asset('build/global.css') }}">
+    + <link rel="stylesheet" href="{{ asset('build/app.css') }}">