Added docs site

Author: Jake Ginnivan

ConventionTests.sln

@@ -7,6 +7,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		appveyor.yml = appveyor.yml
 		GitVersionConfig.yaml = GitVersionConfig.yaml
+		mkdocs.yml = mkdocs.yml
 		README.md = README.md
 	EndProjectSection
 EndProject
@@ -29,6 +30,14 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp", "Samples\Sample
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp.Tests", "Samples\SampleApp.Tests\SampleApp.Tests.csproj", "{8FEF48A8-6FF5-4B65-B84A-6690D735C703}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{D822A12B-D358-48BC-8158-EB5CC253C858}"
+	ProjectSection(SolutionItems) = preProject
+		Docs\defining-conventions.md = Docs\defining-conventions.md
+		Docs\index.md = Docs\index.md
+		mkdocs.yml = mkdocs.yml
+		Docs\symmetric-conventions.md = Docs\symmetric-conventions.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

Docs/defining-conventions.md

@@ -0,0 +1,50 @@
+---
+layout: layout
+title: Defining Conventions
+---
+
+If you want to define your own conventions, it is really easy. 
+
+### Step 1
+Create a new class, inheriting from `IConvention<TData>`, lets use the **must have default constructor** convention as an example
+
+    public class AllClassesHaveDefaultConstructor : IConvention<Types>
+    {
+        public void Execute(Types data, IConventionResult result)
+        {
+        
+        }
+    }
+    
+### Step 2
+Write the convention logic
+
+    var typesWithoutDefaultCtor = data.TypesToVerify.Where(t => t.HasDefaultConstructor() == false);
+    result.Is("Types must have a default constructor", typesWithoutDefaultCtor);
+    
+### Final result
+
+    public class AllClassesHaveDefaultConstructor : IConvention<Types>
+    {
+        public void Execute(Types data, IConventionResult result)
+        {
+            var typesWithoutDefaultCtor = data.TypesToVerify.Where(t => t.HasDefaultConstructor() == false);
+            result.Is("Types must have a default constructor", typesWithoutDefaultCtor);
+        }
+    }
+    
+## IConventionResult
+Currently convention tests supports two types of convention results, the one we have just seen is a normal result. The other type is a symmetric result, which is the result for a symmetric convention.
+
+An example of a symmetric convention is `ClassTypeHasSpecificNamespace`. It can verify a particular class type (dto, domain object, event handler) lives in a certain namespace, but it will also verify that ONLY that class type lives in that namespace. `new ClassTypeHasSpecificNamespace(t => t.Name.EndsWith("Dto"), "TestAssembly.Dtos", "Dto")`
+
+The result will look like this:
+
+    result.IsSymmetric(
+        string.Format("{0}s must be under the '{1}' namespace", classType, namespaceToCheck),
+        string.Format("Non-{0}s must not be under the '{1}' namespace", classType, namespaceToCheck),
+        classIsApplicable,
+        TypeLivesInSpecifiedNamespace,
+        data.TypesToVerify);
+
+See [Symmetric Conventions](SymmetricConventions.html) for more information.    

Docs/imgs/SymmetricConventions.png

@@ -0,0 +1,65 @@
+---
+
+layout: layout
+
+title: ConventionTests
+---
+
+## What is ConventionTests?
+
+Convention over Configuration is a great way to cut down repetitive boilerplate code. But how do you validate that your code adheres to your conventions?
+
+ConventionTests provides a simple API to build validation rules for creating convention validation tests.
+
+## Getting Started
+It is really easy to get started with ConventionTests, there are a number of included conventions that come out of the box:
+
+ - All Classes Have Default Constructor 
+ - All Methods are Virtual
+ - Class type has specific namespace (for example, all dtos must live in the ProjectName.Dtos namespace)
+ - Files are Embedded Resources
+ - Project does not reference dlls from Bin or Obj directory
+ - Others are being added over time and you can create your own custom ones
+
+### Writing your first Convention test
+
+#### 1. Using your favourite testing framework, create a new test. Lets call it:
+
+`entities_must_have_default_constructor`
+
+#### 2. Define some types to validate against a convention
+
+The following line get a list of all the types in the assembly that contains `SampleDomainClass`.
+
+    var itemsToVerify = Types.InAssemblyOf<SampleDomainClass>();
+    
+There are also overloads to restrict the types to a specific namespace within the assembly.
+
+#### 3. Assert the convention
+
+Now we have a list of types to check, we can use one of the pre-built conventions and check all of the types against this convention:
+
+`Convention.Is(new AllClassesHaveDefaultConstructor(), itemsToVerify);`
+
+#### That's it!
+
+When you run this convention, if any of the types don't meet with the chosen convention, it fails and an exception will be thrown, which will look something like this:
+
+	ConventionFailedException
+	Message = Failed: 'Types must have a default constructor'
+	-----------------------------------------------------------------
+	
+	TestAssembly.ClassWithNoDefaultCtor
+	TestAssembly.ClassWithPrivateDefaultCtor
+
+How cool is that!
+
+### Reporting
+If you would like to use ConventionTests reporting features, you just have to opt in by specifying the reporter you want. This makes it easy to add your own reporters, for example a WikiReporter may be better than the `HtmlReporter`
+
+In your `Properties\AssemblyInfo.cs` file add the reporters you want. This are global reporters which will report the results of all conventions.
+
+    [assembly: ConventionReporter(typeof(HtmlConventionResultsReporter))]
+    [assembly: ConventionReporter(typeof(MarkdownConventionResultsReporter))]
+
+Then if you look in the directory where your test assembly is, there will be an html report called `Conventions.htm`, serving as living documentation!

Docs/index.md

@@ -0,0 +1,33 @@
+---
+layout: layout
+title: Symmetric Conventions
+---
+
+Symmetric conventions will verify a convention and also the inverse of that convention.
+
+An example of a symmetric convention is `ClassTypeHasSpecificNamespace`. It can verify a particular class type (dto, domain object, event handler) lives in a certain namespace, but it will also verify that ONLY that class type lives in that namespace. 
+
+Take a look at the following Venn Diagram
+
+![SymmetricConventions](./imgs/SymmetricConventions.png)
+
+In the above example, let us say 'Dtos must live under Project.Dtos'. This means that all data contains ALL TYPES in the assembly, correct data is a dto living in the Project.Dtos namespace. But we have two failure conditions.
+
+The first is if a Dto is outside the Project.Dtos namespace, the convention fails. The second is if a non-dto class lives inside the Project.Dtos namespace.
+
+### How to use a symmetric convention
+
+    var types = new Types("Types in MyProject")
+    {
+        TypesToVerify = typeof(MyDto).Assembly.GetTypes()
+    };
+    var convention = new ClassTypeHasSpecificNamespace(
+        classIsApplicable: t => t.Name.EndsWith("Dto"), 
+        namespaceToCheck : "MyProject.Dtos", 
+        classType: "Dto");
+    Convention.Is(convention, types);
+    
+As you can see, symmetric conventions are no different to enforce
+
+### Writing a symmetric convention
+See [Defining Conventions](DefiningConventions.html)

Docs/symmetric-conventions.md

@@ -19,20 +19,11 @@ public AutofacRegistrations(IComponentRegistry componentRegistry)
             this.componentRegistry = componentRegistry;
         }
 
-        public string Description
-        {
-            get { return "All AutofacContainer Registrations"; }
-        }
+        public string Description => "All AutofacContainer Registrations";
 
-        public bool HasData
-        {
-            get { return true; }
-        }
+        public bool HasData => true;
 
-        public IComponentRegistry ComponentRegistry
-        {
-            get { return componentRegistry; }
-        }
+        public IComponentRegistry ComponentRegistry => componentRegistry;
 
         public Type GetConcreteType(IComponentRegistration r)
         {

TestStack.ConventionTests.Autofac/AutofacRegistrations.cs

@@ -37,13 +37,8 @@ public void Execute(AutofacRegistrations data, IConventionResultContext result)
             result.Is("Can resolve all types registered with Autofac", failingTypes);
         }
 
-        public string ConventionReason
-        {
-            get
-            {
-                return "Container resolution failings are runtime exceptions, this convention allows you to detect missing registrations faster!";
-            }
-        }
+        public string ConventionReason => 
+            "Container resolution failings are runtime exceptions, this convention allows you to detect missing registrations faster!";
 
         private IEnumerable<Type> GetGenericFactoryTypes(AutofacRegistrations data, IComponentRegistration componentRegistration)
         {

TestStack.ConventionTests.Autofac/CanResolveAllRegisteredServices.cs

@@ -59,7 +59,7 @@ static void Execute<TDataSource>(IConvention<TDataSource> convention, TDataSourc
             IEnumerable<IResultsProcessor> processors, ITestResultProcessor resultProcessor)
             where TDataSource : IConventionData
         {
-            var dataDescription = string.Format("{0} in {1}", data.GetType().GetSentenceCaseName(), data.Description);
+            var dataDescription = $"{data.GetType().GetSentenceCaseName()} in {data.Description}";
             var context = new ConventionContext(dataDescription, Formatters, processors, resultProcessor);
             context.Execute(convention, data);
         }

TestStack.ConventionTests/Convention.cs

@@ -0,0 +1,8 @@
+site_name: ConventionTests
+theme: readthedocs
+repo_url: https://github.com/TestStack/TestStack.ConventionTests
+
+pages:
+- Home: index.md
+- 'Defining Conventions': 'defining-conventions.md'
+- 'Symmetric Conventions': 'symmetric-conventions.md'