First pass at the API site

Author: bradwilson

.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.78.3",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}

.editorconfig

@@ -0,0 +1,12 @@
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf
+
+[*.cs]
+indent_style = tab
+indent_size = 4

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+metadata/**/* eol=crlf

.github/workflows/push-main.yml

@@ -0,0 +1,51 @@
+name: api.xunit.net (CI)
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone source
+        uses: actions/checkout@v4
+
+      - name: Install .NET SDK
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: |
+            9.0.x
+
+      - name: Get .NET information
+        run: dotnet --info
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: "Build target: Build"
+        run: dotnet run --project tools/builder --no-launch-profile -- Build --timing
+
+      - name: "Upload artifact: github-pages"
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,3 @@
+_site/
+**/bin/
+**/obj/

CNAME

@@ -0,0 +1 @@
+api.xunit.net

README.md

@@ -0,0 +1,52 @@
+# About This Project
+
+This project contains the public site for [https://api.xunit.net/](https://api.xunit.net/).
+
+To open an issue for this project, please visit the [core xUnit.net project issue tracker](https://github.com/xunit/xunit/issues).
+
+## Building and Contribution
+
+This site is built with DocFX. We use a C#-based build system.
+
+### Build prerequisites
+
+In order to successfully view the content locally, you will need the following pre-requisites:
+
+* [.NET SDK 9.0](https://dotnet.microsoft.com/download/dotnet/9.0)
+* [Docker](https://docs.docker.com/engine/install/) to host nginx for serving built content locally
+
+We have verified this works using both Windows and Linux.
+
+### Building and serving
+
+To build the static content for the site, run `./build`. This will run DocFX to convert the Markdown and YAML files into static content, under a top-level `_site` folder.
+
+To serve the `_site` folder locally, you can run `./build serve` which will launch nginx in a Docker container, and serve the content [locally on port 4000](http://localhost:4000/).
+
+_Important note: You must rebuild the site manually when making changes either to the site or the metadata. The nginx container merely serves whatever lives in `/_site`._
+
+### Editing the site pages
+
+The site content lives in [`/site`](https://github.com/xunit/api.xunit.net/tree/main/site).
+
+Text editors/IDEs which understand site hierarchy and linking while editing Markdown 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._
+
+### Adding metadata for a new xUnit.net version
+
+The [`/metadata`](https://github.com/xunit/api.xunit.net/tree/main/metadata) folder contains the versions of metadata created by `dotnet docfx metadata` during xUnit.net's CI process.
+
+* Download the `docfx` artifact from the appropriate GitHub Actions build, and unzip it into a new folder under `/metadata` that aligns with the version of the assemblies (i.e., the metadata for the `2.0.1` packages for xUnit.net v3 lives under `/metadata/v3/2.0.1`).
+
+* Update [`/site/toc.yml`](https://github.com/xunit/api.xunit.net/tree/main/site/toc.yml) to add an entry for the new version.
+
+* Create an `index.md` under the `site` tree at the appropriate location for the version. Look at the existing tree and inside one of the existing `index.md` files for an example.
+
+Now you should be able to build the site and view the new API version.
+
+# About xUnit.net
+
+[<img align="right" src="https://xunit.net/images/dotnet-fdn-logo.png" width="100" />](https://www.dotnetfoundation.org/)
+
+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).
+
+For project documentation, please visit the [xUnit.net project home](https://xunit.net/).

build

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+function write_error {
+	echo "error(1): $1" 2>&1
+	exit 1
+}
+
+function guard_bin {
+	builtin type -P "$1" &>/dev/null || write_error "Could not find '$1'; $2"
+}
+
+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 docker "please install Docker from (https://docs.docker.com/engine/install/)"
+
+[ $(dotnet --version | cut -d. -f1) -ge 9 ] || write_error ".NET SDK version $(dotnet --version) is too low; please install version 9.0 (https://dot.net/)"
+
+git submodule status | while read line; do
+	if [ "$(echo $line | cut -b1)" == "-" ]; then
+		pieces=( $line )
+		git submodule update --init ${pieces[1]}
+		echo ""
+	fi
+done
+
+PUSHED=0
+
+cleanup () {
+	if [[ $PUSHED == 1 ]]; then
+		popd >/dev/null
+		PUSHED=0
+	fi
+}
+
+trap cleanup EXIT ERR INT TERM
+
+pushd $( cd "$(dirname "$0")" ; pwd -P ) >/dev/null
+PUSHED=1
+
+dotnet run --project tools/builder --no-launch-profile -- "$@"

build.ps1

@@ -0,0 +1,43 @@
+#!/usr/bin/env pwsh
+#Requires -Version 5.1
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function GuardBin {
+	param (
+		[string]$binary,
+		[string]$message
+	)
+
+	if ($null -eq (Get-Command $binary -ErrorAction Ignore)) {
+		throw "Could not find '$binary'; $message"
+	}
+}
+
+GuardBin git "please install the Git CLI from https://git-scm.com/"
+GuardBin dotnet "please install the .NET SDK from https://dot.net/"
+GuardBin npm "please install Node and npm from (https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)"
+GuardBin docker "please install Docker from (https://docs.docker.com/engine/install/)"
+
+$version = [Version]$([regex]::matches((&dotnet --version), '^(\d+\.)?(\d+\.)?(\*|\d+)').value)
+if ($version.Major -lt 9) {
+	throw ".NET SDK version ($version) is too low; please install version 9.0 from https://dot.net/"
+}
+
+& git submodule status | ForEach-Object {
+	if ($_[0] -eq '-') {
+		$pieces = $_.Split(' ')
+		& git submodule update --init "$($pieces[1])"
+		Write-Host ""
+	}
+}
+
+Push-Location (Split-Path $MyInvocation.MyCommand.Definition)
+
+try {
+	& dotnet run --project tools/builder --no-launch-profile -- $args
+}
+finally {
+	Pop-Location
+}

global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "9.0.100",
+    "rollForward": "latestMinor"
+  }
+}