Updated README.md, plus make NodeJS/Docker optional

Author: bradwilson

README.md

@@ -6,36 +6,53 @@ To open an issue for this project, please visit the [core xUnit.net project issu
 
 ## Building and Contribution
 
-This site is built with Jekyll, which is based on Ruby, as this is the default system used by GitHub Pages. We use a C#-based build system.
+This site is built with DocFX. We use a C#-based build system.
 
 ### Build prerequisites
 
 In order to successfully build and view the content locally, you will need the following pre-requisites:
 
 * [.NET SDK 9 or later](https://dotnet.microsoft.com/download/dotnet/)
-* [NodeJS 22 or later](https://nodejs.org/) for live content rebuild during development
-* [Docker](https://docs.docker.com/engine/install/) to host nginx during development
+
+If you wish to use `./build serve` for live regeneration during development, you will also need:
+
+* [NodeJS 22 or later](https://nodejs.org/) (for the live rebuild monitoring)
+* [Docker](https://docs.docker.com/engine/install/) (to host nginx)
 
 ### Editing the site pages
 
 The site content lives in [`/site`](https://github.com/xunit/xunit.net/tree/main/site) and the output will placed in `/.site`. To build the static content, run the command `./build` from the root of your clone, via your command prompt (bash and PowerShell are supported). This will do a one-time transformation of the templates in `/site` to the static files in `/.site`.
 
-For working interactively, you can run `./build serve` which will start Jekyll in a mode where it incrementally builds the site as needed, and will rebuild pages as you change the files. You can point your browser to [http://localhost:4000/](http://localhost:4000/) while the server is running to view the rendered content. Once you're finished, you can press Ctrl+C in the command prompt and the server will shut down.
-
-_Note: if you see a warning about `Auto-regeneration may not work on some Windows versions` and you're running in WSL 2, you may safely ignore this. Auto-regeneration works in WSL 2 without issue, and the warning is based on some very early WSL 1 bugs with file system watchers._
+For working interactively, you can run `./build serve` which will use NodeJS to run in a mode where it simultaneously builds the site and uses a Docker-based nginx server to serve the static content. It will automatically rebuild the site as you change the site's content files. You can point your browser to [http://127.0.0.1:4000/](http://127.0.0.1:4000/) while the server is running to view the rendered content. Once you're finished, you can press Ctrl+C in the command prompt and the server will shut down. (You may need to press Ctrl+C more than once on Windows.)
 
 Text editors/IDEs which understand site hierarchy and linking while editing Markdown and HTML are strongly encouraged to open the `/site` folder and not the root folder when editing content, so that the editor understands where the content root lives. _For example, if you're using VSCode, you should run `code site` and not `code .` from the root of the repo._ You should only ever need to open the root of the repo in your editor if you're working on the build tools.
 
-### Editing analyzer rule documentation
+# About xUnit.net
 
-The analyzer rules are does as Markdown templates that live in [`/site/xunit.analyzers/_rules`](site/xunit.analyzers/_rules) and are rendered dynamically into [`/site/xunit.analyzers/_rules`](site/xunit.analyzers/rules).
+xUnit.net is a free, open source, community-focused unit testing tool for C#, F#, and Visual Basic.
 
-The standard template for creating documentation for a new rule lives in [`/site/xunit.analyzers/_rules/_stub.md`](site/xunit.analyzers/_rules/_stub.md). Copy this file and name it to match the analyzer ID (note: these are case-sensitive, so they should always have names like `xUnit0000.md` where `0000` is the rule number). Fill out the document header and contents, and ensure the rule shows up in the [Analyzer Rules](http://localhost:4000/xunit.analyzers/rules) home page. Ensure that the page renders properly, as you may need to quote values in the header if they contain characters that Jekyll does not to process when running the template engine. You can use an existing documentation page to understand what an analyzer documentation page should look like.
+xUnit.net works with the [.NET SDK](https://dotnet.microsoft.com/download) command line tools, [Visual Studio](https://visualstudio.microsoft.com/), [Visual Studio Code](https://code.visualstudio.com/), [JetBrains Rider](https://www.jetbrains.com/rider/), [NCrunch](https://www.ncrunch.net/), and any development environment compatible with [Microsoft Testing Platform](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro) (xUnit.net v3) or [VSTest](https://github.com/microsoft/vstest) (all versions of xUnit.net).
 
-# About xUnit.net
+xUnit.net is part of the [.NET Foundation](https://www.dotnetfoundation.org/) and operates under their [code of conduct](https://www.dotnetfoundation.org/code-of-conduct). It is licensed under [Apache 2](https://opensource.org/licenses/Apache-2.0) (an OSI approved license). The project is [governed](https://xunit.net/governance) by a Project Lead.
 
-[<img align="right" src="https://xunit.net/images/dotnet-fdn-logo.png" width="100" />](https://www.dotnetfoundation.org/)
+For project documentation, please visit the [xUnit.net project home](https://xunit.net/).
 
-xUnit.net is a free, open source, community-focused unit testing tool for the .NET Framework. Written by the original inventor of NUnit v2, xUnit.net is the latest technology for unit testing C#, F#, VB.NET and other .NET languages. xUnit.net works with ReSharper, CodeRush, TestDriven.NET and Xamarin. It is part of the [.NET Foundation](https://www.dotnetfoundation.org/), and operates under their [code of conduct](https://dotnetfoundation.org/about/policies/code-of-conduct). It is licensed under [Apache 2](https://opensource.org/licenses/Apache-2.0) (an OSI approved license).
+* _New to xUnit.net? Get started with the [.NET SDK](https://xunit.net/docs/getting-started/v3/getting-started)._
+* _Need some help building the source? See [BUILDING.md](https://github.com/xunit/xunit/tree/main/BUILDING.md)._
+* _Want to contribute to the project? See [CONTRIBUTING.md](https://github.com/xunit/.github/tree/main/CONTRIBUTING.md)._
+* _Want to contribute to the assertion library? See the [suggested contribution workflow](https://github.com/xunit/assert.xunit/tree/main/README.md#suggested-contribution-workflow) in the assertion library project, as it is slightly more complex due to code being spread across two GitHub repositories._
 
-For project documentation, please visit the [xUnit.net project home](https://xunit.net/).
+## Latest Builds
+
+|                             | Latest stable                                                                                                                            | Latest CI ([how to use](https://xunit.net/docs/using-ci-builds))                                                                                                                                                                          | Build status
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------
+| `xunit.v3`                  | [![](https://img.shields.io/nuget/v/xunit.v3.svg?logo=nuget)](https://www.nuget.org/packages/xunit.v3)                                   | [![](https://img.shields.io/badge/endpoint.svg?url=https://f.feedz.io/xunit/xunit/shield/xunit.v3/latest&color=f58142)](https://feedz.io/org/xunit/repository/xunit/packages/xunit.v3)                                   | [![](https://img.shields.io/endpoint.svg?url=https://actions-badge.atrox.dev/xunit/xunit/badge%3Fref%3Dmain&amp;label=build)](https://actions-badge.atrox.dev/xunit/xunit/goto?ref=main)
+| `xunit`                     | [![](https://img.shields.io/nuget/v/xunit.svg?logo=nuget)](https://www.nuget.org/packages/xunit)                                         | [![](https://img.shields.io/badge/endpoint.svg?url=https://f.feedz.io/xunit/xunit/shield/xunit/latest&color=f58142)](https://feedz.io/org/xunit/repository/xunit/packages/xunit)                                         | [![](https://img.shields.io/endpoint.svg?url=https://actions-badge.atrox.dev/xunit/xunit/badge%3Fref%3Dv2&amp;label=build)](https://actions-badge.atrox.dev/xunit/xunit/goto?ref=v2)
+| `xunit.analyzers`           | [![](https://img.shields.io/nuget/v/xunit.analyzers.svg?logo=nuget)](https://www.nuget.org/packages/xunit.analyzers)                     | [![](https://img.shields.io/badge/endpoint.svg?url=https://f.feedz.io/xunit/xunit/shield/xunit.analyzers/latest&color=f58142)](https://feedz.io/org/xunit/repository/xunit/packages/xunit.analyzers)                     | [![](https://img.shields.io/endpoint.svg?url=https://actions-badge.atrox.dev/xunit/xunit.analyzers/badge%3Fref%3Dmain&amp;label=build)](https://actions-badge.atrox.dev/xunit/xunit.analyzers/goto?ref=main)
+| `xunit.runner.visualstudio` | [![](https://img.shields.io/nuget/v/xunit.runner.visualstudio.svg?logo=nuget)](https://www.nuget.org/packages/xunit.runner.visualstudio) | [![](https://img.shields.io/badge/endpoint.svg?url=https://f.feedz.io/xunit/xunit/shield/xunit.runner.visualstudio/latest&color=f58142)](https://feedz.io/org/xunit/repository/xunit/packages/xunit.runner.visualstudio) | [![](https://img.shields.io/endpoint.svg?url=https://actions-badge.atrox.dev/xunit/visualstudio.xunit/badge%3Fref%3Dmain&amp;label=build)](https://actions-badge.atrox.dev/xunit/visualstudio.xunit/goto?ref=main)
+
+*For complete CI package lists, please visit the [feedz.io package search](https://feedz.io/org/xunit/repository/xunit/search). A free login is required.*
+
+## Sponsors
+
+Help support this project by becoming a sponsor through [GitHub Sponsors](https://github.com/sponsors/xunit).

build

@@ -12,7 +12,6 @@ function guard_bin {
 
 guard_bin git "please install the Git CLI from https://git-scm.com/"
 guard_bin dotnet "please install the .NET SDK from https://dot.net/"
-guard_bin node "please install NodeJS from https://nodejs.org/"
 
 [ $(dotnet --version | cut -d. -f1) -ge 9 ] || write_error ".NET SDK version $(dotnet --version) is too low; please install version 9.0 from https://dot.net/"
 

build.ps1

@@ -17,7 +17,6 @@ function GuardBin {
 
 GuardBin git "please install the Git CLI from https://git-scm.com/"
 GuardBin dotnet "please install the .NET SDK from https://dot.net/"
-GuardBin node "please install NodeJS from https://nodejs.org/"
 
 $version = [Version]$([regex]::matches((&dotnet --version), '^(\d+\.)?(\d+\.)?(\*|\d+)').value)
 if ($version.Major -lt 9) {

tools/builder/models/BuildTarget.cs

@@ -3,6 +3,7 @@ namespace Xunit.BuildTools.Models;
 public class BuildTarget
 {
 	public const string Build = nameof(Build);
-	public const string Restore = nameof(Restore);
+	public const string RestoreDotNet = nameof(RestoreDotNet);
+	public const string RestoreNode = nameof(RestoreNode);
 	public const string Serve = nameof(Serve);
 }

tools/builder/targets/Build.cs

@@ -5,7 +5,7 @@ namespace Xunit.BuildTools.Targets;
 
 [Target(
 	BuildTarget.Build,
-	BuildTarget.Restore
+	BuildTarget.RestoreDotNet
 )]
 public static class Build
 {

tools/builder/targets/RestoreDotNet.cs

@@ -0,0 +1,15 @@
+using System.Threading.Tasks;
+using Xunit.BuildTools.Models;
+
+namespace Xunit.BuildTools.Targets;
+
+[Target(BuildTarget.RestoreDotNet)]
+public static partial class RestoreDotNet
+{
+	public static async Task OnExecute(BuildContext context)
+	{
+		context.BuildStep("Restoring .NET build environment");
+
+		await context.Exec("dotnet", "tool restore");
+	}
+}

tools/builder/targets/Restore.cs tools/builder/targets/RestoreNode.cstools/builder/targets/Restore.cs renamed to tools/builder/targets/RestoreNode.cs

@@ -4,14 +4,12 @@
 
 namespace Xunit.BuildTools.Targets;
 
-[Target(BuildTarget.Restore)]
-public static partial class RestoreTools
+[Target(BuildTarget.RestoreNode)]
+public static partial class RestoreNode
 {
 	public static async Task OnExecute(BuildContext context)
 	{
-		context.BuildStep("Restoring build environment");
-
-		await context.Exec("dotnet", "tool restore");
+		context.BuildStep("Restoring NodeJS build environment");
 
 		if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
 			await context.Exec("cmd", "/c npm install --no-fund");

tools/builder/targets/Serve.cs

@@ -7,7 +7,7 @@ namespace Xunit.BuildTools.Targets;
 
 [Target(
 	BuildTarget.Serve,
-	BuildTarget.Restore
+	BuildTarget.RestoreDotNet, BuildTarget.RestoreNode
 )]
 public static class Serve
 {