Add runnable example for Spies documentation - Resolves #2040

.markdownlintrc

@@ -10,7 +10,7 @@
     "punctuation": ".,;:!"
   },
   "MD033": {
-    "allowed_elements": ["dl", "dt", "dd", "code", "var"]
+    "allowed_elements": ["dl", "dt", "dd", "code", "var", "div"]
   },
   "first-line-h1": false,
   "no-hard-tabs": true,

docs/_includes/embed-scripts.html

@@ -0,0 +1,21 @@
+{% for example in page.examples %}
+    {% assign filename = 'examples/' | append: example | append: '.stub' %}
+    <template data-example-script="{{ example }}">{% include_relative {{filename}} %}</template>
+    <script>
+        (function(){
+            // get script example div
+            var element = document.querySelector("[data-example-id={{ example }}]");
+
+            // get script example source from the template
+            var scriptTemplate = document.querySelector("[data-example-script={{ example }}]");
+
+            var notebook = RunKit.createNotebook({
+                // the parent element for the new notebook
+                element: element,
+                // specify the source of the notebook
+                source: scriptTemplate.innerHTML,
+                theme: "untilted-c3qcs6lijfuc"
+            });
+        })(); // IIFE - to avoid leaking variables
+    </script>
+{% endfor %}

docs/_includes/footer.html

@@ -1,4 +1,6 @@
 <script src="{{ "/assets/js/prism.js" | prepend: site.baseurl }}"></script>
+<script src="https://embed.runkit.com"></script>
+{% include embed-scripts.html %}
 
 <div class="footer">
   <div class="container text-center">

docs/release-source/release/examples/spies-1-pubsub.stub

@@ -0,0 +1,16 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assertTrue = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers on publish", function () {
+        var callback = sinon.spy();
+
+        PubSub.subscribe("message", callback);
+        PubSub.publishSync("message");
+
+        assertTrue(callback.called);
+    })
+});

docs/release-source/release/examples/spies-2-wrap-object-methods.stub

@@ -0,0 +1,31 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Wrap all object method', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery);
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.getJSON(url);
+
+        assert(jQuery.ajax.calledOnce);
+        assert.equals(url, jQuery.ajax.getCall(0).args[0].url);
+        assert.equals("json", jQuery.ajax.getCall(0).args[0].dataType);
+    })
+});

docs/release-source/release/examples/spies-3-wrap-existing-method.stub

@@ -0,0 +1,31 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Wrap existing method', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery, "ajax");
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.getJSON(url);
+
+        assert(jQuery.ajax.calledOnce);
+        assert.equals(url, jQuery.ajax.getCall(0).args[0].url);
+        assert.equals("json", jQuery.ajax.getCall(0).args[0].dataType);
+    })
+});

docs/release-source/release/examples/spies-4-pubsub-message-1.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert(spy.calledWith(message));
+    })
+});

docs/release-source/release/examples/spies-5-pubsub-message-2.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert.equals(message, spy.args[0][0]);
+    })
+});

docs/release-source/release/examples/spies-6-pubsub-message-3.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var PubSub = require("pubsub-js");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('PubSub', function() {
+    it("should call subscribers with message as first argument", function () {
+        var message = 'an example message';
+        var spy = sinon.spy();
+
+        PubSub.subscribe(message, spy);
+        PubSub.publishSync(message, "some payload");
+
+        assert.equals(message, spy.getCall(0).args[0]);
+    })
+});

docs/release-source/release/examples/spies-7-with-args.stub

@@ -0,0 +1,17 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+
+describe('withArgs', function() {
+    it("should call method once with each argument", function () {
+        var object = { method: function () {} };
+        var spy = sinon.spy(object, "method");
+
+        object.method(42);
+        object.method(1);
+
+        assert(spy.withArgs(42).calledOnce);
+        assert(spy.withArgs(1).calledOnce);
+    })
+});

docs/release-source/release/examples/spies-8-spy-call.stub

@@ -0,0 +1,30 @@
+require("@fatso83/mini-mocha").install();
+var sinon = require("sinon");
+var referee = require("@sinonjs/referee");
+var assert = referee.assert;
+var jsdom = require('jsdom');
+var JSDOM = jsdom.JSDOM;
+var window = (new JSDOM()).window;
+var document = (new JSDOM('')).window;
+var jQuery = require('jquery')(window);
+global.document = document;
+
+describe('Return nth call', function() {
+    var sandbox = sinon.createSandbox();
+
+    beforeEach(function() {
+        sandbox.spy(jQuery, "ajax");
+    });
+
+    afterEach(function() {
+        sandbox.restore();
+    });
+
+    it("should inspect jQuery.getJSON's usage of jQuery.ajax", function () {
+        var url = "https://jsonplaceholder.typicode.com/todos/1";
+        jQuery.ajax(url);
+        var spyCall = jQuery.ajax.getCall(0);
+
+        assert.equals(url, spyCall.args[0]);
+    })
+});

docs/release-source/release/spies.md

@@ -2,6 +2,15 @@
 layout: page
 title: Spies - Sinon.JS
 breadcrumb: spies
+examples:
+- spies-1-pubsub
+- spies-2-wrap-object-methods
+- spies-3-wrap-existing-method
+- spies-4-pubsub-message-1
+- spies-5-pubsub-message-2
+- spies-6-pubsub-message-3
+- spies-7-with-args
+- spies-8-spy-call
 ---
 
 ### Introduction
@@ -21,16 +30,7 @@ anonymous function spy. The spy won't do anything except record information
 about its [calls][call]. A common use case for this type of spy is testing how a function
 handles a callback, as in the following simplified example:
 
-```javascript
-"test should call subscribers on publish": function () {
-    var callback = sinon.spy();
-    PubSub.subscribe("message", callback);
-
-    PubSub.publishSync("message");
-
-    assertTrue(callback.called);
-}
-```
+<div data-example-id="spies-1-pubsub"></div>
 
 ### Using a spy to wrap all object method
 
@@ -42,29 +42,9 @@ Note that it's usually better practice to spy individual methods, particularly o
 
 Spying individual methods tests intent more precisely and is less susceptible to unexpected behavior as the object's code evolves.
 
- The following is a slightly contrived example:
-
-```javascript
-{
-    sandbox: sinon.createSandbox(),
-
-    setUp: function () {
-        this.sandbox.spy(jQuery);
-    },
-
-    tearDown: function () {
-        this.sandbox.restore(); // Unwraps all spied methods
-    },
+The following is a slightly contrived example:
 
-    "test should inspect jQuery.getJSON's usage of jQuery.ajax": function () {
-        jQuery.getJSON("/some/resource");
-
-        assert(jQuery.ajax.calledOnce);
-        assertEquals("/some/resource", jQuery.ajax.getCall(0).args[0].url);
-        assertEquals("json", jQuery.ajax.getCall(0).args[0].dataType);
-    }
-}
-```
+<div data-example-id="spies-2-wrap-object-methods"></div>
 
 
 ### Using a spy to wrap an existing method
@@ -74,25 +54,7 @@ Spying individual methods tests intent more precisely and is less susceptible to
 (including when used as a constructor), but you will have access to data about
 all [calls][call]. The following is a slightly contrived example:
 
-```javascript
-{
-    setUp: function () {
-        sinon.spy(jQuery, "ajax");
-    },
-
-    tearDown: function () {
-        jQuery.ajax.restore(); // Unwraps the spy
-    },
-
-    "test should inspect jQuery.getJSON's usage of jQuery.ajax": function () {
-        jQuery.getJSON("/some/resource");
-
-        assert(jQuery.ajax.calledOnce);
-        assertEquals("/some/resource", jQuery.ajax.getCall(0).args[0].url);
-        assertEquals("json", jQuery.ajax.getCall(0).args[0].dataType);
-    }
-}
-```
+<div data-example-id="spies-3-wrap-existing-method"></div>
 
 
 ### Creating spies: `sinon.spy()` Method Signatures
@@ -128,44 +90,14 @@ because it keeps your test from being too specific about which call did what and
 so on. It will return `true` if the spy was ever called with the provided
 arguments.
 
-```javascript
-"test should call subscribers with message as first argument" : function () {
-    var message = 'an example message';
-    var spy = sinon.spy();
-
-    PubSub.subscribe(message, spy);
-    PubSub.publishSync(message, "some payload");
-
-    assert(spy.calledWith(message));
-}
-```
+<div data-example-id="spies-4-pubsub-message-1"></div>
 
 If you want to be specific, you can directly check the first argument of the
 first [call][call]. There are two ways of achieving this:
 
-```javascript
-"test should call subscribers with message as first argument" : function () {
-    var message = 'an example message';
-    var spy = sinon.spy();
-
-    PubSub.subscribe(message, spy);
-    PubSub.publishSync(message, "some payload");
-
-    assertEquals(message, spy.args[0][0]);
-}
-```
-
-```javascript
-"test should call subscribers with message as first argument" : function () {
-    var message = 'an example message';
-    var spy = sinon.spy();
+<div data-example-id="spies-5-pubsub-message-2"></div>
 
-    PubSub.subscribe(message, spy);
-    PubSub.publishSync(message, "some payload");
-
-    assertEquals(message, spy.getCall(0).args[0]);
-}
-```
+<div data-example-id="spies-6-pubsub-message-3"></div>
 
 The first example uses the two-dimensional `args` array directly on the spy,
 while the second example fetches the first [call][call] object and then accesses its
@@ -187,18 +119,7 @@ are also available on `object.method`.
 
 Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call].
 
-```javascript
-"should call method once with each argument": function () {
-    var object = { method: function () {} };
-    var spy = sinon.spy(object, "method");
-
-    object.method(42);
-    object.method(1);
-
-    assert(spy.withArgs(42).calledOnce);
-    assert(spy.withArgs(1).calledOnce);
-}
-```
+<div data-example-id="spies-7-with-args"></div>
 
 
 #### `spy.callCount`
@@ -394,13 +315,7 @@ Returns the *nth* [call](#spycall).
 
 Accessing individual calls helps with more detailed behavior verification when the spy is called more than once.
 
-```javascript
-sinon.spy(jQuery, "ajax");
-jQuery.ajax("/stuffs");
-var spyCall = jQuery.ajax.getCall(0);
-
-assertEquals("/stuffs", spyCall.args[0]);
-```
+<div data-example-id="spies-8-spy-call"></div>
 
 
 #### `var spyCalls = spy.getCalls();`