Overhaul the grid system and its docs

* Add new grid mixins adapted from Preboot (http://github.com/mdo/preboot)
* Drop the @grid-row-width and @grid-column-width variables
* Add the @grid-float-breakpoint variable, as used in Preboot
* Add support for .push* and .pull* classes for column ordering manipulation
* Document all the things

2 files changed, 165 insertions, 18 deletions

diff --git a/docs/assets/css/bootstrap.css b/docs/assets/css/bootstrap.css
index b7b304014e..26dddb1b8a 100644
--- a/docs/assets/css/bootstrap.css
+++ b/docs/assets/css/bootstrap.css
@@ -741,8 +741,8 @@ pre code {
 }
 
 .row {
-  margin-right: -10px;
-  margin-left: -10px;
+  margin-right: -15px;
+  margin-left: -15px;
 }
 
 .row:before,
@@ -756,9 +756,10 @@ pre code {
 }
 
 [class^="span"] {
+  position: relative;
   min-height: 1px;
-  padding-right: 10px;
-  padding-left: 10px;
+  padding-right: 15px;
+  padding-left: 15px;
 }
 
 @media screen and (min-width: 768px) {
@@ -840,6 +841,78 @@ pre code {
   .offset1 {
     margin-left: 8.333333333333332%;
   }
+  .push12 {
+    left: 100%;
+  }
+  .push11 {
+    left: 91.66666666666666%;
+  }
+  .push10 {
+    left: 83.33333333333334%;
+  }
+  .push9 {
+    left: 75%;
+  }
+  .push8 {
+    left: 66.66666666666666%;
+  }
+  .push7 {
+    left: 58.333333333333336%;
+  }
+  .push6 {
+    left: 50%;
+  }
+  .push5 {
+    left: 41.66666666666667%;
+  }
+  .push4 {
+    left: 33.33333333333333%;
+  }
+  .push3 {
+    left: 25%;
+  }
+  .push2 {
+    left: 16.666666666666664%;
+  }
+  .push1 {
+    left: 8.333333333333332%;
+  }
+  .pull12 {
+    right: 100%;
+  }
+  .pull11 {
+    right: 91.66666666666666%;
+  }
+  .pull10 {
+    right: 83.33333333333334%;
+  }
+  .pull9 {
+    right: 75%;
+  }
+  .pull8 {
+    right: 66.66666666666666%;
+  }
+  .pull7 {
+    right: 58.333333333333336%;
+  }
+  .pull6 {
+    right: 50%;
+  }
+  .pull5 {
+    right: 41.66666666666667%;
+  }
+  .pull4 {
+    right: 33.33333333333333%;
+  }
+  .pull3 {
+    right: 25%;
+  }
+  .pull2 {
+    right: 16.666666666666664%;
+  }
+  .pull1 {
+    right: 8.333333333333332%;
+  }
 }
 
 @media screen and (min-width: 992px) {
@@ -852,14 +925,6 @@ pre code {
   .container {
     max-width: 1170px;
   }
-  .row {
-    margin-right: -15px;
-    margin-left: -15px;
-  }
-  [class^="span"] {
-    padding-right: 15px;
-    padding-left: 15px;
-  }
 }
 
 [class*="span"].pull-right {
diff --git a/docs/css.html b/docs/css.html
index fd6faa1734..2116ad3d82 100644
--- a/docs/css.html
+++ b/docs/css.html
@@ -23,7 +23,7 @@ title: CSS
           <li><a href="#global"><i class="glyphicon glyphicon-chevron-right"></i> Global settings</a></li>
           <li><a href="#typography"><i class="glyphicon glyphicon-chevron-right"></i> Typography</a></li>
           <li><a href="#code"><i class="glyphicon glyphicon-chevron-right"></i> Code</a></li>
-          <li><a href="#grid-system"><i class="glyphicon glyphicon-chevron-right"></i> Grid system</a></li>
+          <li><a href="#grid"><i class="glyphicon glyphicon-chevron-right"></i> Grid system</a></li>
           <li><a href="#tables"><i class="glyphicon glyphicon-chevron-right"></i> Tables</a></li>
           <li><a href="#forms"><i class="glyphicon glyphicon-chevron-right"></i> Forms</a></li>
           <li><a href="#buttons"><i class="glyphicon glyphicon-chevron-right"></i> Buttons</a></li>
@@ -468,13 +468,13 @@ title: CSS
 
         <!-- Grid system
         ================================================== -->
-        <section id="grid-system">
+        <section id="grid">
           <div class="page-header">
             <h1>Grid system</h1>
           </div>
-          <p class="lead">Bootstrap utilizes a responsive, percent-based grid system, that scales up appropriately as devices and viewport sizes increase. In other words, it's mobile first.</p>
+          <p class="lead">Bootstrap includes a responsive, percent-based grid system that appropriately scales up to 12 columns as the device or viewport size increases&mdash;in other words, it's mobile first. It includes <a href="#grid-example">predefined classes</a> for this, as well as powerful <a href="#grid-less">mixins for generating semantic layouts</a>.</p>
 
-          <h3>Grid example</h3>
+          <h3 id="grid-example">Grid example</h3>
           <p>On mobile devices, the grid starts out stacked. Above 768px, it becomes horizontal as media queries kick in to apply <code>float</code>s and <code>width</code>s. To create a basic grid layout, wrap a series of <code>.span*</code> elements within a <code>.row</code>. As this is a 12-column grid, each <code>.span*</code> spans a number of those 12 columns, and should always add up to 12 for each row (or the number of columns in the parent), even at mobile resolutions.</p>
           <div class="bs-docs-grid">
             <div class="row show-grid">
@@ -527,7 +527,7 @@ title: CSS
 </div>
 {% endhighlight %}
 
-          <h2>Offsetting columns</h2>
+          <h3 id="grid-offsetting">Offsetting columns</h3>
           <p>Move columns to the right using <code>.offset*</code> classes. Each class increases the left margin of a column by a whole column. For example, <code>.offset4</code> moves <code>.span4</code> over four columns.</p>
           <div class="bs-docs-grid">
             <div class="row show-grid">
@@ -550,7 +550,7 @@ title: CSS
 {% endhighlight %}
 
 
-          <h2>Nesting columns</h2>
+          <h3 id="grid-nesting">Nesting columns</h3>
           <p>To nest your content with the default grid, add a new <code>.row</code> and set of <code>.span*</code> columns within an existing <code>.span*</code> column. Nested rows should include a set of columns that add up to 12.</p>
           <div class="row show-grid">
             <div class="span9">
@@ -581,6 +581,88 @@ title: CSS
 </div>
 {% endhighlight %}
 
+          <h3 id="grid-column-ordering">Column ordering</h3>
+          <p>Easily the order of our built-in grid columns with <code>.push*</code> and <code>.pull*</code> modifier classes.</p>
+<div class="row show-grid">
+  <div class="span9 push3">9</div>
+  <div class="span3 pull9">3</div>
+</div>
+
+{% highlight html linenos %}
+<div class="row show-grid">
+  <div class="span9 push3">9</div>
+  <div class="span3 pull9">3</div>
+</div>
+{% endhighlight %}
+
+          <h3 id="grid-less">LESS mixins and variables</h3>
+          <p>In addition to <a href="#grid-example">prebuilt grid classes</a> for fast layouts, Bootstrap includes LESS variables and mixins for quickly generating your own simple, semantic layouts.</p>
+
+          <h4>Variables</h4>
+          <p>Variables determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.</p>
+{% highlight css linenos %}
+@grid-columns:              12;
+@grid-gutter-width:         30px;
+@grid-float-breakpoint:     768px;
+{% endhighlight %}
+
+          <h4>Mixins</h4>
+          <p>Mixins are used in conjunction with the grid variables to generate semantic CSS for individual grid columns.</p>
+{% highlight css linenos %}
+// Creates a wrapper for a series of columns
+.make-row() {
+  // Negative margin the row out to align the content of columns
+  margin-left:  (@grid-gutter-width / -2);
+  margin-right: (@grid-gutter-width / -2);
+  // Then clear the floated columns
+  .clear_float();
+}
+
+// Generate the columns
+.make-column(@columns) {
+  @media (min-width: @grid-float-breakpoint) {
+    float: left;
+    // Calculate width based on number of columns available
+    width: percentage(@columns / @grid-columns);
+  }
+  // Prevent columns from collapsing when empty
+  min-height: 1px;
+  // Set inner padding as gutters instead of margin
+  padding-left:  (@grid-gutter-width / 2);
+  padding-right: (@grid-gutter-width / 2);
+}
+
+// Generate the column offsets
+.make-column-offset(@columns) {
+  @media (min-width: @grid-float-breakpoint) {
+    margin-left: percentage((@columns / @grid-columns));
+  }
+}
+{% endhighlight %}
+
+          <h4>Example usage</h4>
+          <p>You can modify the variables to your own custom values, or just use the mixins with their default values. Here's an example of using the default settings to create a two-column layout with a gap between.</p>
+{% highlight css linenos %}
+.wrapper {
+  .make-row();
+}
+.content-main {
+  .make-column(8);
+}
+.content-secondary {
+  .make-column(3);
+  .make-column-offset(1);
+}
+{% endhighlight %}
+{% highlight html linenos %}
+<div class="wrapper">
+  <div class="content-main">...</div>
+  <div class="content-secondary">...</div>
+</div>
+{% endhighlight %}
+
+
+
         </section>