Merge pull request #347 from JakeGinnivan/ShouldNotBeDocs

Switched ShouldNotBe docs over to use examples, moved approved files …

docs/assertions/shouldBe.rst

@@ -5,76 +5,76 @@ Objects
 -------
 ``ShouldBe`` works on all types and compares using ``.Equals``.
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Objects.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/Objects.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Objects.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/Objects.exceptionText.approved.txt
 
 Numeric
 -------
 ``ShouldBe`` numeric overloads accept tolerances and has overloads for ``float``, ``double`` and ``decimal`` types.
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Numeric.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/Numeric.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Numeric.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/Numeric.exceptionText.approved.txt
 
 DateTime(Offset)
 ----------------
 DateTime overloads are similar to the numeric overloads and support tolerances.
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/DateTime.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/DateTime.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/DateTime.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/DateTime.exceptionText.approved.txt
 
 TimeSpan
 --------
 TimeSpan also has tolerance overloads
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/TimeSpanExample.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/TimeSpanExample.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/TimeSpanExample.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/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
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/Enumerables.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/Enumerables.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/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.
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/EnumerablesOfNumerics.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/EnumerablesOfNumerics.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/EnumerablesOfNumerics.exceptionText.approved.txt
 
 
 Bools
 -----
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/BooleanExample.codeSample.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/BooleanExample.codeSample.approved.txt
 	:language: c#
 
 **Exception**
 
-.. literalinclude:: /../src/DocumentationExamples/CodeExamples/BooleanExample.exceptionText.approved.txt
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldBe/BooleanExample.exceptionText.approved.txt

docs/assertions/shouldNotBe.rst

@@ -7,80 +7,56 @@ Objects
 -------
 ``ShouldNotBe`` works on all types and compares using ``.Equals``.
 
-.. code-block:: c#
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/Objects.codeSample.approved.txt
+	:language: c#
 
-  var theSimpsonsCat = new Cat() { Name = "Santas little helper" };
-  theSimpsonsCat.Name.ShouldNotBe("Santas little helper");
+**Exception**
 
-Exception::
-
-  theSimpsonsCat.Name
-      should not be
-  "Santas little helper"
-      but was
-  "Santas little helper"
-
-Want to contribute to Shouldly? `#304 <https://github.com/shouldly/shouldly/issues/304>`_ makes this error message better!
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/Objects.exceptionText.approved.txt
 
 Numeric
 -------
 ``ShouldNotBe`` also allows you to compare numeric values, regardless of their value type.
 
-.. code-block:: c#
-
-  const int one = 1;
-  one.ShouldNotBe(1)
+Integer
+```````
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/NumericInt.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  one should not be 1 but was 1
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/NumericInt.exceptionText.approved.txt
 
-.. code-block:: c#
+Long
+````
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/NumericLong.codeSample.approved.txt
+	:language: c#
 
-  const long aLong = 1L;
-  aLong.ShouldNotBe(1);
+**Exception**
 
-Exception::
-
-  aLong should not be 1 but was 1
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/NumericLong.exceptionText.approved.txt
 
 DateTime(Offset)
 ----------------
 ``ShouldNotBe`` DateTime overloads are similar to the numeric overloads and also support tolerances.
 
-.. code-block:: c#
-
-  var date = new DateTime(2000, 6, 1);
-  date.ShouldNotBe(new DateTime(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1.5));
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/DateTime.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  date
-      should not be within
-  01:30:00
-      of
-  01/06/2000 01:00:01
-      but was
-  01/06/2000 00:00:00
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/DateTime.exceptionText.approved.txt
 
 TimeSpan
 --------
 
 ``TimeSpan`` also has tolerance overloads
 
-.. code-block:: c#
-
-  var timeSpan = TimeSpan.FromHours(1);
-  timeSpan.ShouldNotBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1.5d));
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/TimeSpanExample.codeSample.approved.txt
+	:language: c#
 
-Exception::
+**Exception**
 
-  timeSpan
-      should not be within
-  01:30:00
-      of
-  02:06:00
-      but was
-  01:00:00
+.. literalinclude:: /../src/DocumentationExamples/CodeExamples/ShouldNotBe/TimeSpanExample.exceptionText.approved.txt
 
 Want to contribute to Shouldly? `#303 <https://github.com/shouldly/shouldly/issues/303>`_ makes this error message better!

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

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

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

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

src/DocumentationExamples/CodeExamples/ShouldNotBeExamples/NumericInt.codeSample.approved.txt

@@ -0,0 +1,2 @@
+const int one = 1;
+one.ShouldNotBe(1);

src/DocumentationExamples/CodeExamples/ShouldNotBeExamples/NumericInt.exceptionText.approved.txt

@@ -0,0 +1,4 @@
+one
+    should not be
+1
+    but was

src/DocumentationExamples/CodeExamples/ShouldNotBeExamples/NumericLong.codeSample.approved.txt

@@ -0,0 +1,2 @@
+const long aLong = 1L;
+aLong.ShouldNotBe(1);

src/DocumentationExamples/CodeExamples/ShouldNotBeExamples/NumericLong.exceptionText.approved.txt

@@ -0,0 +1,4 @@
+aLong
+    should not be
+1L
+    but was

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

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

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

@@ -0,0 +1,4 @@
+theSimpsonsCat.Name
+    should not be
+"Santas little helper"
+    but was

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

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

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

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

src/DocumentationExamples/DocExampleWriter.cs

@@ -9,6 +9,7 @@
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Shouldly;
+using Xunit.Abstractions;
 
 namespace DocumentationExamples
 {
@@ -18,7 +19,7 @@ public static class DocExampleWriter
             new ConcurrentDictionary<string, List<MethodDeclarationSyntax>>();
 
         [MethodImpl(MethodImplOptions.NoInlining)]
-        public static void Document(Action shouldMethod)
+        public static void Document(Action shouldMethod, ITestOutputHelper testOutputHelper)
         {
             var stackTrace = new StackTrace(true);
             var caller = stackTrace.GetFrame(1);
@@ -48,19 +49,33 @@ public static void Document(Action shouldMethod)
             var body = string.Join(string.Empty, enumerable);
             var exceptionText = Should.Throw<ShouldAssertException>(shouldMethod).Message;
 
+            testOutputHelper.WriteLine("Docs body:");
+            testOutputHelper.WriteLine("");
+            testOutputHelper.WriteLine(body);
+            testOutputHelper.WriteLine("");
+            testOutputHelper.WriteLine("");
+            testOutputHelper.WriteLine("Exception text:");
+            testOutputHelper.WriteLine("");
+            testOutputHelper.WriteLine(exceptionText);
+
+
+            var approvedFileFolder = $"CodeExamples/{callerMethod.DeclaringType.Name}";
             try
             {
                 body.ShouldMatchApproved(c => c
                     .WithDescriminator("codeSample")
                     .UseCallerLocation()
-                    .SubFolder("CodeExamples"));
+                    .SubFolder(approvedFileFolder));
             }
             finally
             {
-                exceptionText.ShouldMatchApproved(c => c
-                    .WithDescriminator("exceptionText")
-                    .UseCallerLocation()
-                    .SubFolder("CodeExamples"));
+                exceptionText.ShouldMatchApproved(c =>
+                {
+                    c
+                        .WithDescriminator("exceptionText")
+                        .UseCallerLocation()
+                        .SubFolder(approvedFileFolder);
+                });
             }
         }
     }

src/DocumentationExamples/DocumentationExamples.csproj

@@ -82,6 +82,7 @@
   </ItemGroup>
   <ItemGroup>
     <Compile Include="DocExampleWriter.cs" />
+    <Compile Include="ShouldNotBeExamples.cs" />
     <Compile Include="ShouldBeExamples.cs" />
     <Compile Include="ExampleClasses.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />

src/DocumentationExamples/ShouldBeExamples.cs

@@ -5,19 +5,27 @@
 using Shouldly;
 using Simpsons;
 using Xunit;
+using Xunit.Abstractions;
 
 namespace DocumentationExamples
 {
     public class ShouldBeExamples
     {
+        readonly ITestOutputHelper _testOutputHelper;
+
+        public ShouldBeExamples(ITestOutputHelper testOutputHelper)
+        {
+            _testOutputHelper = testOutputHelper;
+        }
+
         [Fact]
         public void Objects()
         {
             DocExampleWriter.Document(() =>
-                {
-                    var theSimpsonsCat = new Cat { Name = "Santas little helper" };
-                    theSimpsonsCat.Name.ShouldBe("Snowball 2");
-                });
+            {
+                var theSimpsonsCat = new Cat { Name = "Santas little helper" };
+                theSimpsonsCat.Name.ShouldBe("Snowball 2");
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -27,7 +35,7 @@ public void Numeric()
             {
                 const decimal pi = (decimal)Math.PI;
                 pi.ShouldBe(3.24m, 0.01m);
-            });
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -38,7 +46,7 @@ public void DateTime()
             {
                 var date = new DateTime(2000, 6, 1);
                 date.ShouldBe(new DateTime(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1));
-            });
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -48,7 +56,7 @@ public void TimeSpanExample()
             {
                 var timeSpan = TimeSpan.FromHours(1);
                 timeSpan.ShouldBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1));
-            });
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -63,7 +71,7 @@ public void Enumerables()
                 var theBeSharps = new List<Person> { homer, skinner, barney };
 
                 theBeSharps.ShouldBe(new[] { apu, homer, skinner, barney });
-            });
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -74,7 +82,7 @@ public void EnumerablesOfNumerics()
                 var firstSet = new[] { 1.23m, 2.34m, 3.45001m };
                 var secondSet = new[] { 1.4301m, 2.34m, 3.45m };
                 firstSet.ShouldBe(secondSet, 0.1m);
-            });
+            }, _testOutputHelper);
         }
 
         [Fact]
@@ -84,7 +92,7 @@ public void BooleanExample()
             {
                 const bool myValue = false;
                 myValue.ShouldBe(true, "Some additional context");
-            });
+            }, _testOutputHelper);
         }
     }
 }