Build up the docfx site and create a package README

README.md

@@ -4,57 +4,49 @@ Xunit.SkippableFact
 [![GitHub Actions status](https://github.com/aarnott/Library.Template/workflows/CI/badge.svg)](https://github.com/AArnott/Xunit.SkippableFact/actions/workflows/build.yml)
 [![NuGet package](https://img.shields.io/nuget/v/xunit.skippablefact.svg)](https://nuget.org/packages/xunit.skippablefact)
 
-This project allows for Xunit tests that can determine during execution
-that they should report a "skipped" result. This can be useful when
-a precondition is not satisfied, or the test is over functionality that
-does not exist on the platform being tested.
+This project allows for Xunit tests that can determine during execution that they should report a "skipped" result.
+This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested.
 
 ## Installation
 
 This project is available as a [NuGet package][NuPkg]
 
-## Example
+## Usage
+
+[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/).
+
+Below is a sampling of uses.
+
+Skip based on a runtime check:
 
 ```csharp
 [SkippableFact]
-public void SomeTestForWindowsOnly()
+public void SomeMoodyTest()
 {
-    Skip.IfNot(Environment.IsWindows);
-
-    // Test Windows only functionality.
+    Skip.IfNot(InTheMood);
 }
 ```
 
-You can also automatically report tests as skipped based on specific exception types.
-This is particularly useful when the test runs against multiple target frameworks and
-your library is not expected to be implemented in some of them. For example:
+Skip based on a thrown exception:
 
 ```csharp
-[SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))]
+[SkippableFact(typeof(NotSupportedException))]
 public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms()
 {
     // Test functionality. If it throws any of the exceptions listed in the attribute,
     // a skip result is reported instead of a failure.
 }
 ```
 
-## The `[SupportedOSPlatform]` attribute
-
-Since version 1.5, `Xunit.SkippableFact` understands the `SupportedOSPlatform` attribute to skip tests on unsupported platforms.
+Skip based on `SupportedOSPlatformAttribute`:
 
 ```csharp
 [SkippableFact, SupportedOSPlatform("Windows")]
 public void TestCngKey()
 {
-    var key = CngKey.Create(CngAlgorithm.Sha256);
+    var key = CngKey.Create(CngAlgorithm.Rsa);
     Assert.NotNull(key);
 }
 ```
 
-Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger:
-> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'.
-
-Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS.
-
 [NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact
-[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416

Xunit.SkippableFact.sln

@@ -1,4 +1,4 @@
-Microsoft Visual Studio Solution File, Format Version 12.00
+Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 15
 VisualStudioVersion = 15.0.26228.9
 MinimumVisualStudioVersion = 10.0.40219.1
@@ -22,6 +22,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Xunit.SkippableFact.Tests", "test\Xunit.SkippableFact.Tests\Xunit.SkippableFact.Tests.csproj", "{B6E55EBE-4D2D-48DE-97AF-6058169B517D}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Samples", "samples\Samples.csproj", "{115DBEC6-9D00-4070-82C3-C17D3F508EE0}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -36,6 +38,10 @@ Global
 		{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

docfx/docs/features.md

@@ -1,3 +1,6 @@
 # Features
 
-TODO
+* Report tests as skipped instead of as pass or fail when the inputs, the operating system, or other factors render the test invalid or not applicable.
+* A test result can be "Skipped" based on a runtime check within the test, an attribute on the test method, or a throwing one or more particular exceptions.
+* Support for skipping facts or individual test cases in theories.
+* Optionally provide the reason for a test being skipped for inclusion in the test log.

docfx/docs/getting-started.md

@@ -5,8 +5,40 @@
 Consume this library via its NuGet Package.
 Click on the badge to find its latest version and the instructions for consuming it that best apply to your project.
 
-[![NuGet package](https://img.shields.io/nuget/v/Library.svg)](https://nuget.org/packages/Library)
+[![NuGet package](https://img.shields.io/nuget/v/Xunit.SkippableFact.svg)](https://nuget.org/packages/Xunit.SkippableFact)
 
 ## Usage
 
-TODO
+Always use the @Xunit.SkippableFactAttribute or @Xunit.SkippableTheoryAttribute on test methods that you want to potentially skip for.
+
+### Conditional runtime skipping
+
+Use methods on the @Xunit.Skip class to skip a test based on some runtime check.
+
+This can be useful when you need to test for specific runtime conditions.
+It can also be useful to skip certain test cases in a theory when input combinations are invalid.
+
+[!code-csharp[](../../samples/GettingStarted.cs#RuntimeCheck)]
+
+### Exceptions thrown
+
+You can also automatically report tests as skipped based on specific exception types.
+This is particularly useful when the test runs against multiple target frameworks and
+your library is not expected to be implemented in some of them. For example:
+
+[!code-csharp[](../../samples/GettingStarted.cs#ThrownExceptions)]
+
+### Supported platforms
+
+Apply the @System.Runtime.Versioning.SupportedOSPlatformAttribute and/or @System.Runtime.Versioning.UnsupportedOSPlatformAttribute to a test method to skip it based on the platform the test is running on.
+
+[!code-csharp[](../../samples/GettingStarted.cs#OSCheck)]
+
+Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger:
+
+> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'.
+
+Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS.
+
+[NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact
+[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416

docfx/index.md

@@ -4,6 +4,7 @@ _layout: landing
 
 # Overview
 
-This is your docfx landing page.
+This project allows for Xunit tests that can determine during execution that they should report a "skipped" result.
+This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested.
 
-Click "Docs" across the top to get get started.
+Click "Docs" across the top to get started.

samples/.editorconfig

@@ -0,0 +1,55 @@
+[*.cs]
+
+# SA1123: Do not place regions within elements
+dotnet_diagnostic.SA1123.severity = none
+
+# SA1124: Do not use regions
+dotnet_diagnostic.SA1124.severity = none
+
+# SA1133: Do not combine attributes
+dotnet_diagnostic.SA1133.severity = silent
+
+# SA1200: Using directives should be placed correctly
+dotnet_diagnostic.SA1200.severity = none
+
+# SA1201: Elements should appear in the correct order
+dotnet_diagnostic.SA1201.severity = silent
+
+# SA1205: Partial elements should declare access
+dotnet_diagnostic.SA1205.severity = none
+
+# SA1400: Access modifier should be declared
+dotnet_diagnostic.SA1400.severity = none
+
+# SA1402: File may only contains a single type
+dotnet_diagnostic.SA1402.severity = none
+
+# SA1403: File may only contain a single namespace
+dotnet_diagnostic.SA1403.severity = none
+
+# SA1502: Element should not be on a single line
+dotnet_diagnostic.SA1502.severity = none
+
+# SA1515: Single-line comment should be preceded by blank line
+dotnet_diagnostic.SA1515.severity = none
+
+# SA1516: Elements should be separated by blank line
+dotnet_diagnostic.SA1516.severity = none
+
+# SA1600: Elements should be documented
+dotnet_diagnostic.SA1600.severity = silent
+
+# SA1601: Partial elements should be documented
+dotnet_diagnostic.SA1601.severity = silent
+
+# SA1649: File name should match first type name
+dotnet_diagnostic.SA1649.severity = none
+
+# IDE0051: Remove unused private members
+dotnet_diagnostic.IDE0051.severity = none
+
+# CS1591: Missing XML comment for publicly visible type or member
+dotnet_diagnostic.CS1591.severity = silent
+
+# CA1822: Mark members as static
+dotnet_diagnostic.CA1822.severity = silent

samples/GettingStarted.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Andrew Arnott. All rights reserved.
+// Licensed under the Microsoft Public License (Ms-PL). See LICENSE.txt file in the project root for full license information.
+
+using System.Runtime.InteropServices;
+using System.Runtime.Versioning;
+using System.Security.Cryptography;
+using Xunit;
+
+public class GettingStarted
+{
+    #region RuntimeCheck
+    [SkippableFact]
+    public void RuntimeCheck()
+    {
+        Skip.IfNot(Environment.GetEnvironmentVariable("RunThisTest") == "true");
+    }
+    #endregion
+
+    #region ThrownExceptions
+    [SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))]
+    public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms()
+    {
+        // Test functionality. If it throws any of the exceptions listed in the attribute,
+        // a skip result is reported instead of a failure.
+    }
+    #endregion
+
+    #region OSCheck
+    [SkippableFact, SupportedOSPlatform("Windows")]
+    public void TestCngKey()
+    {
+        var key = CngKey.Create(CngAlgorithm.Rsa);
+        Assert.NotNull(key);
+    }
+    #endregion
+}

samples/Samples.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\src\Xunit.SkippableFact\Xunit.SkippableFact.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+  </ItemGroup>
+
+</Project>

src/Xunit.SkippableFact/README.md

@@ -0,0 +1,8 @@
+# Xunit.SkippableFact
+
+This library allows for Xunit tests that can determine during execution that they should report a "skipped" result.
+This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested.
+
+Use `[SkippableFact]` or `[SkippableTheory]` to make a test skippable.
+
+[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/).