Merge pull request #345 from JakeGinnivan/DocsWork

Created documentation samples project which outputs files to be inclu…

docs/assertions/shouldBe.rst

@@ -5,132 +5,76 @@ Objects
 -------
 ``ShouldBe`` works on all types and compares using ``.Equals``.
 
-.. code-block:: c#
-
-  var theSimpsonsCat = new Cat() { Name = "Santas little helper" };
-  theSimpsonsCat.Name.ShouldBe("Snowball 2");
-
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Objects.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  theSimpsonsCat.Name
-      should be
-  "Snowball 2"
-      but was
-  "Santas little helper"
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Objects.exceptionText.approved.txt
 
 Numeric
 -------
 ``ShouldBe`` numeric overloads accept tolerances and has overloads for ``float``, ``double`` and ``decimal`` types.
 
-.. code-block:: c#
-
-  const decimal pi = (decimal)Math.PI;
-  pi.ShouldBe(3.24m, 0.01m);
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Numeric.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  pi
-     should be within
-  0.01
-      of
-  3.24
-      but was
-  3.14159265358979
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Numeric.exceptionText.approved.txt
 
 DateTime(Offset)
 ----------------
 DateTime overloads are similar to the numeric overloads and support tolerances.
 
-.. code-block:: c#
-
-  var date = new DateTime(2000, 6, 1);
-  date.ShouldBe(new DateTime(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1));
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/DateTime.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  date
-     should be within
-  01:00:00
-      of
-  1/06/2000 1:00:01 AM
-      but was
-  1/06/2000 12:00:00 AM
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/DateTime.exceptionText.approved.txt
 
 TimeSpan
 --------
 TimeSpan also has tolerance overloads
 
-.. code-block:: c#
-
-  var timeSpan = TimeSpan.FromHours(1);
-  timeSpan.ShouldBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1));
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/TimeSpanExample.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  timeSpan
-     should be within
-  01:00:00
-      of
-  02:06:00
-      but was
-  01:00:00
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/TimeSpanExample.exceptionText.approved.txt
 
 Want to improve shouldy? We have an open issue at [#303](https://github.com/shouldly/shouldly/issues/303) to improve this error message!
 
 Enumerables
 -----------
 Enumerable comparison is done on the elements in the enumerable, so you can compare an array to a list and have it pass.
 
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Enumerables.codeSample.approved.txt
+	:language: c#
 
-.. code-block:: c#
-
-  var apu = new Person() { Name = "Apu" };
-  var homer = new Person() { Name = "Homer" };
-  var skinner = new Person() { Name = "Skinner" };
-  var barney = new Person() { Name = "Barney" };
-  var theBeSharps = new List<Person>() { homer, skinner, barney };
-
-  theBeSharps.ShouldBe(new[] {apu, homer, skinner, barney});
-
-Exception::
+**Exception**
 
-  theBeSharps
-      should be
-  [Apu, Homer, Skinner, Barney]
-      but was
-  [Homer, Skinner, Barney]
-      difference
-  [*Homer*, *Skinner*, *Barney*, *]
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Enumerables.exceptionText.approved.txt
 
 Enumerables of Numerics
 -----------------------
 If you have enumerables of ``float``, ``decimal`` or ``double`` types then you can use the tolerance overloads, similar to the value extensions.
 
-.. code-block:: c#
-
-  var firstSet = new[] { 1.23m, 2.34m, 3.45001m };
-  var secondSet = new[] { 1.4301m, 2.34m, 3.45m };
-  firstSet.ShouldBe(secondSet, 0.1m);
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  firstSet
-     should be within
-  0.1
-      of
-  [1.4301, 2.34, 3.45]
-      but was
-  [1.23, 2.34, 3.45001]
-      difference
-  [*1.23*, 2.34, *3.45001*]
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.exceptionText.approved.txt
 
 
 Bools
 -----
-.. literalinclude:: /../src/Shouldly.Tests/ShouldBe/BoolScenario.cs
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/BooleanExample.codeSample.approved.txt
 	:language: c#
-	:linenos:
-	:lines: 7-16
-	:dedent: 8
-	:emphasize-lines: 3,9
+
+**Exception**
+
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/BooleanExample.exceptionText.approved.txt

docs/configuration.rst

@@ -0,0 +1,27 @@
+Configuration
+=============
+
+Shouldly has a few configuration options:
+
+DefaultFloatingPointTolerance
+-----------------------------
+
+Allows specifying a floating point tolerance for all assertions
+
+**Default value:** 0.0d
+
+DefaultTaskTimeout
+------------------
+:code:`Should.Throw(Func<Task>)` blocks, the timeout is a safeguard for deadlocks.
+
+Shouldly runs the lambda without a synchronisation context, but deadlocks are still possible. Use :code:`Should.ThrowAsync` to be safe then await the returned task to prevent possible deadlocks.
+
+**Default value:** 10 seconds
+
+CompareAsObjectTypes
+--------------------
+Types which also are IEnumerable of themselves.
+
+An example is :code:`Newtonsoft.Json.Linq.JToken` which looks like this :code:`class JToken : IEnumerable<JToken>`.
+
+**Default value:** Newtonsoft.Json.Linq.JToken

docs/exampleClasses.rst

@@ -3,48 +3,5 @@ Example Classes
 
 The classes used in these samples are:
 
-.. code-block:: c#
-
-  namespace Simpsons
-  {
-      public abstract class Pet
-      {
-          public abstract string Name { get; set; }
-
-          public override string ToString()
-          {
-              return Name;
-          }
-      }
-  }
-
-  namespace Simpsons
-  {
-      public class Cat : Pet
-      {
-          public override string Name { get; set; }
-      }
-  }
-
-  namespace Simpsons
-  {
-      public class Dog : Pet
-      {
-          public override string Name { get; set; }
-      }
-  }
-
-  namespace Simpsons
-  {
-      public class Person
-      {
-          public string Name { get; set; }
-          public int Salary { get; set; }
-
-
-          public override string ToString()
-          {
-              return Name;
-          }
-      }
-  }
+.. literalinclude:: /../src/DocumentationExamples/ExampleClasses.cs
+	:language: c#

docs/index.rst

@@ -58,6 +58,7 @@ Shouldly has plenty of different assertions, have a look under the assertions fo
    assertions/shouldNotBe
    exampleClasses
    contributing
+   configuration
 
 
 Indices and tables

src/DocumentationExamples/CodeExamples/BooleanExample.codeSample.approved.txt

@@ -0,0 +1,2 @@
+const bool myValue = false;
+myValue.ShouldBe(true, "Some additional context");

src/DocumentationExamples/CodeExamples/BooleanExample.exceptionText.approved.txt

@@ -0,0 +1,8 @@
+myValue
+    should be
+True
+    but was
+False
+
+Additional Info:
+    Some additional context

src/DocumentationExamples/CodeExamples/DateTime.codeSample.approved.txt

@@ -0,0 +1,2 @@
+var date = new DateTime(2000, 6, 1);
+date.ShouldBe(new DateTime(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1));

src/DocumentationExamples/CodeExamples/DateTime.exceptionText.approved.txt

@@ -0,0 +1,7 @@
+date
+    should be within
+01:00:00
+    of
+1/06/2000 1:00:01 AM
+    but was
+1/06/2000 12:00:00 AM

src/DocumentationExamples/CodeExamples/Enumerables.codeSample.approved.txt

@@ -0,0 +1,6 @@
+var apu = new Person { Name = "Apu" };
+var homer = new Person { Name = "Homer" };
+var skinner = new Person { Name = "Skinner" };
+var barney = new Person { Name = "Barney" };
+var theBeSharps = new List<Person> { homer, skinner, barney };
+theBeSharps.ShouldBe(new[] { apu, homer, skinner, barney });

src/DocumentationExamples/CodeExamples/Enumerables.exceptionText.approved.txt

@@ -0,0 +1,7 @@
+theBeSharps
+    should be
+[Apu, Homer, Skinner, Barney]
+    but was
+[Homer, Skinner, Barney]
+    difference
+[*Homer*, *Skinner*, *Barney*, *]

src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.codeSample.approved.txt

@@ -0,0 +1,3 @@
+var firstSet = new[] { 1.23m, 2.34m, 3.45001m };
+var secondSet = new[] { 1.4301m, 2.34m, 3.45m };
+firstSet.ShouldBe(secondSet, 0.1m);

src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.exceptionText.approved.txt

@@ -0,0 +1,9 @@
+firstSet
+    should be within
+0.1m
+    of
+[1.4301m, 2.34m, 3.45m]
+    but was
+[1.23m, 2.34m, 3.45001m]
+    difference
+[*1.23m*, 2.34m, *3.45001m*]

src/DocumentationExamples/CodeExamples/Numeric.codeSample.approved.txt

@@ -0,0 +1,2 @@
+const decimal pi = (decimal)Math.PI;
+pi.ShouldBe(3.24m, 0.01m);

src/DocumentationExamples/CodeExamples/Numeric.exceptionText.approved.txt

@@ -0,0 +1,7 @@
+pi
+    should be within
+0.01m
+    of
+3.24m
+    but was
+3.14159265358979m

src/DocumentationExamples/CodeExamples/Objects.codeSample.approved.txt

@@ -0,0 +1,2 @@
+var theSimpsonsCat = new Cat { Name = "Santas little helper" };
+theSimpsonsCat.Name.ShouldBe("Snowball 2");

src/DocumentationExamples/CodeExamples/Objects.exceptionText.approved.txt

@@ -0,0 +1,13 @@
+theSimpsonsCat.Name
+    should be
+"Snowball 2"
+    but was
+"Santas little helper"
+    difference
+Difference     |       |    |    |    |    |    |         |    |    |    |    |    |    |    |    |    |    |    |   
+               |      \|/  \|/  \|/  \|/  \|/  \|/       \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  
+Index          | 0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   
+Expected Value | S    n    o    w    b    a    l    l    \s   2                                                      
+Actual Value   | S    a    n    t    a    s    \s   l    i    t    t    l    e    \s   h    e    l    p    e    r    
+Expected Code  | 83   110  111  119  98   97   108  108  32   50                                                     
+Actual Code    | 83   97   110  116  97   115  32   108  105  116  116  108  101  32   104  101  108  112  101  114  

src/DocumentationExamples/CodeExamples/TimeSpanExample.codeSample.approved.txt

@@ -0,0 +1,2 @@
+var timeSpan = TimeSpan.FromHours(1);
+timeSpan.ShouldBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1));

src/DocumentationExamples/CodeExamples/TimeSpanExample.exceptionText.approved.txt

@@ -0,0 +1,7 @@
+timeSpan
+    should be within
+01:00:00
+    of
+02:06:00
+    but was
+01:00:00