[WIP] Documentation for focused specs.

css/style.css

@@ -24,7 +24,6 @@ a:active {
 
  ul {
  	list-style:circle;
- 	list-style-position: inside;
  	margin: 0;
  	padding: 0;
  }
@@ -84,9 +83,12 @@ a.btn {
 /*****************
  * Reference List
  *****************/
+.reference-list li {
+	margin-left: 20px;
+	padding-bottom: 10px;
+}
 .reference-list p {
-	margin:0 0 20px 0;
-	padding-left:18px;
+	margin:10px 0;
 	width:300px;
 }
 
@@ -252,4 +254,4 @@ a.btn {
 	 .nav > .dropdown {
 	 	display:none;
 	 }
-}
+}

events.html

@@ -22,7 +22,6 @@ <h1 class="text-center">Peridot Events</h1>
         //let your loved ones know about your shortcomings?
     });
 }
-?>
 {% endhighlight %}
 
 <p>The following events are available for your testing pleasure:</p>
@@ -34,7 +33,7 @@ <h1 class="text-center">Peridot Events</h1>
             Fires when the Peridot application is constructed. Useful for defining additional CLI arguments and options.
         </p>
         <p>
-            <strong>Arguments:</strong><br> 
+            <strong>Arguments:</strong><br>
             <a target="_blank" href="/docs/class-Peridot.Console.Environment.html">Environment</a> <code>$environment</code><br>
             <a target="_blank" href="/docs/class-Peridot.Console.Application.html">Application</a> <code>$application</code>
         </p>
@@ -45,7 +44,7 @@ <h1 class="text-center">Peridot Events</h1>
             Fires when the Peridot application is configured. Useful for overriding configuration values and configuring the Peridot test runner.
         </p>
         <p>
-            <strong>Arguments:</strong><br> 
+            <strong>Arguments:</strong><br>
     <a target="_blank" href="/docs/class-Peridot.Configuration.html">Configuration</a> <code>$configuration</code><br>
             <a target="_blank" href="/docs/class-Peridot.Console.Application.html">Application</a> <code>$application</code>
         </p>

index.html

@@ -1,7 +1,6 @@
 ---
 layout: default
 title: Event driven BDD test framework for PHP!
-peridot_version: ~1.15
 type: index
 ---
 
@@ -50,13 +49,13 @@ <h2 id="installation">Installing Peridot</h2>
         <h3>Composer</h3>
 {% highlight bash %}
 # global composer install
-$ composer global require peridot-php/peridot:{{ page.peridot_version }}
+$ composer global require peridot-php/peridot
 
 # ensure .composer/vendor/bin is on your PATH
 $ export PATH="$PATH:$HOME/.composer/vendor/bin"
 
 # local per project install (recommended)
-$ composer require peridot-php/peridot:{{ page.peridot_version }}
+$ composer require peridot-php/peridot
 {% endhighlight %}
 
         <h3>Manual install</h3>
@@ -83,22 +82,23 @@ <h2 id="getting-started">Getting Started</h2>
             Peridot uses the familiar <code>describe-it</code> syntax to create a clear and readable testing language.
         </p>
 
-{% highlight php %}
-<?php //arrayobject.spec.php
+{% highlight php startinline %}
+// arrayobject.spec.php
 describe('ArrayObject', function() {
     beforeEach(function() {
         $this->arrayObject = new ArrayObject(['one', 'two', 'three']);
     });
 
     describe('->count()', function() {
-        it("should return the number of items", function() {
+        it('should return the number of items', function() {
             $count = $this->arrayObject->count();
-            assert($count === 3, "expected 3");
+            assert($count === 3, 'expected 3');
         });
     });
 });
-?>
+{% endhighlight %}
 
+{% highlight console %}
 $ peridot arrayobject.spec.php
 
   ArrayObject
@@ -107,54 +107,87 @@ <h2 id="getting-started">Getting Started</h2>
 
 
   1 passing (19 ms)
-
 {% endhighlight %}
 
         <h2 id="peridot-cli"><code class="code">peridot</code></h2>
 
-<pre>
+{% highlight console %}
+$ peridot --help
 Usage:
- peridot [options] [files]
+  peridot [options] [files]
 
 Options:
- --grep (-g)          Run tests matching &lt;pattern&gt; (default: *.spec.php)
- --no-colors (-C)     Disable output colors
- --reporter (-r)      Select which reporter to use (default: spec)
- --bail (-b)          Stop on failure
- --configuration (-c) A php file containing peridot configuration
- --reporters          List all available reporters
- --version (-V)       Display the Peridot version number
- --help (-h)          Display this help message.
-</pre>
+  -f, --focus=FOCUS                  Run tests matching <pattern>
+  -s, --skip=SKIP                    Skip tests matching <pattern>
+  -g, --grep=GREP                    Run tests with filenames matching <pattern> (default: *.spec.php)
+  -b, --bail                         Stop on failure
+  -r, --reporter=REPORTER            Select which reporter to use (default: spec)
+      --reporters                    List all available reporters
+  -C, --no-colors                    Disable output colors
+      --force-colors                 Force output colors
+  -c, --configuration=CONFIGURATION  A php file containing peridot configuration
+  -V, --version                      Display the Peridot version number
+  -h, --help                         Display this help message.
+{% endhighlight %}
+
+        <h3>-f, --focus</h3>
+        <p>
+            Only run tests whose title matches the provided pattern. See <a href="#focusing-and-skipping">Focusing and Skipping</a>.
+        </p>
+
+        <h3>-s, --skip</h3>
+        <p>
+            Only run tests whose title does not match the provided pattern. See <a href="#focusing-and-skipping">Focusing and Skipping</a>.
+        </p>
 
         <h3>-g, --grep</h3>
         <p>
-            Only run test files whose name matches the provided pattern. The default grep pattern is <code>*.spec.php</code>
+            Only run test files whose filename matches the provided pattern. The default grep pattern is <code>*.spec.php</code>
         </p>
 
-        <h3>-C, --no-colors</h3>
+        <h3>-b, --bail</h3>
         <p>
-            Disable colors in output.
+            Tell peridot to stop running tests as soon as there is a failure.
         </p>
 
         <h3>-r, --reporter</h3>
         <p>
             Select which reporter to use. This is the reporter name registered via <a target="_blank" href="http://peridot-php.github.io/docs/class-Peridot.Reporter.ReporterFactory.html">ReporterFactory::register</a>.
         </p>
 
-        <h3>-b, --bail</h3>
+        <h3>--reporters</h3>
         <p>
-            Tell peridot to stop running tests as soon as there is a failure.
+            List available test reporters.
+        </p>
+
+        <h3>-C, --no-colors</h3>
+        <p>
+            Disable colors in output.
         </p>
 
         <h3>-c, --configuration</h3>
         <p>
             A path to a peridot configuration file. Defaults to <code>getcwd() . '/peridot.php'</code>
         </p>
 
-        <h3>--reporters</h3>
+        <h2 id="focusing-and-skipping">Focusing and Skipping</h3>
+
+        <p>See also <a href="syntax.html#focused-specs">Focused Specs</a>, which allow you to focus tests without using command line options.</p>
         <p>
-            List available test reporters.
+            The <code>--focus</code> and <code>--skip</code> options can be used independently, or combined for complex test isolation.
+            If both are used, <code>--skip</code> will take precedence.
+        </p>
+        <p>
+            The patterns accepted by both of these options are PCRE regular expressions that are evaluated against the "title" of the test.
+            The test title includes the description of the suite it is contained within, including any ancestors of that suite.
+            For example, the test shown in <a href="#getting-started">Getting Started</a> has a title of: <code>ArrayObject ->count() should return the number of items</code>.
+        </p>
+        <p>
+            If the provided pattern is not a complete PCRE regular expression, it will be surrounded in delimiters.
+            For example, <code>--focus 'foo.*'</code> is equivalent to <code>--focus '~\bfoo.*\b~'</code>.
+            If the provided pattern is not a valid PCRE regular expression, it will be treated as plain text.
+            For example, <code>--focus 'foo('</code> is equivalent to <code>--focus '~\bfoo\(\b~'</code>.
+            The addition of <code>\b</code> simply prevents accidental matching of substrings.
         </p>
 
         <h2 id="examples">Example Test Suites</h2>
@@ -173,8 +206,8 @@ <h2 id="peridot-tests">Running Peridot's tests</h2>
             Peridot's tests were written using Peridot. After cloning Peridot, you can run tests using:
         </p>
 
-{% highlight bash %}
-$ bin/peridot specs/
+{% highlight console %}
+$ bin/peridot
 {% endhighlight %}
     </div>
 </div>

plugins.html

@@ -21,7 +21,6 @@ <h1 class="text-center">Plugins</h1>
         //do something with the failed test
     });
 }
-?>
 {% endhighlight %}
 
 <p>

scopes.html

@@ -49,25 +49,22 @@ <h1 class="text-center">Scopes</h1>
         $test->getScope()->peridotAddChildScope($driverScope);
     });
 }
-?>
 {% endhighlight %}
 
         <p>
             By mixing the <code>WebDriverScope</code> in to our test's scopes, we have made the following possible in our tests:
         </p>
 
-{% highlight php %}
-<?php
+{% highlight php startinline %}
 describe('The home page', function() {
     it('should have a greeting', function() {
         $this->getPage('http://localhost:4000');
         $greeting = $this->findElementById('greeting');
         assert($greeting->getText() === "Hello", "should be Hello");
     });
 });
-?>
 {% endhighlight %}
 
 <p>
-    Scopes are a powerful concept, and one that should be used liberally to simplify your tests. You can use them to easily include helpers and behavior for your tests, whether that is across the <a href="https://github.com/peridot-php/peridot-prophecy-plugin/blob/master/src/ProphecyPlugin.php#L31" target="__blank">entire suite</a>, or for a <a href="https://github.com/peridot-php/peridot-concurrency/blob/master/specs/runner/stream-select/application/TestMessageReader.php" target="__blank">few select tests</a>. 
-</p>
+    Scopes are a powerful concept, and one that should be used liberally to simplify your tests. You can use them to easily include helpers and behavior for your tests, whether that is across the <a href="https://github.com/peridot-php/peridot-prophecy-plugin/blob/master/src/ProphecyPlugin.php#L31" target="__blank">entire suite</a>, or for a <a href="https://github.com/peridot-php/peridot-concurrency/blob/master/specs/runner/stream-select/application/TestMessageReader.php" target="__blank">few select tests</a>.
+</p>