Add docfx site placeholder

.config/dotnet-tools.json

@@ -6,19 +6,29 @@
       "version": "7.4.6",
       "commands": [
         "pwsh"
-      ]
+      ],
+      "rollForward": false
     },
     "dotnet-coverage": {
       "version": "17.12.6",
       "commands": [
         "dotnet-coverage"
-      ]
+      ],
+      "rollForward": false
     },
     "nbgv": {
       "version": "3.6.146",
       "commands": [
         "nbgv"
-      ]
+      ],
+      "rollForward": false
+    },
+    "docfx": {
+      "version": "2.77.0",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
     }
   }
 }

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: 📚 Docs
+
+on:
+  push:
+    branches:
+    - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: ⚙ Install prerequisites
+      run: ./init.ps1 -UpgradePrerequisites
+
+    - run: dotnet docfx doc/github.io/docfx.json
+      name: 📚 Generate documentation
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: doc/github.io/_site
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -40,3 +40,12 @@ This repository can be built on Windows, Linux, and OSX.
 Building, testing, and packing this repository can be done by using the standard dotnet CLI commands (e.g. `dotnet build`, `dotnet test`, `dotnet pack`, etc.).
 
 [pwsh]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-6
+
+## Tutorial and API documentation
+
+API and hand-written docs are found under the `docfx/` directory. and are built by [docfx](https://dotnet.github.io/docfx/).
+
+You can make changes and host the site locally to preview them by switching to that directory and running the `dotnet docfx --serve` command.
+After making a change, you can rebuild the docs site while the localhost server is running by running `dotnet docfx` again from a separate terminal.
+
+The `.github/workflows/docs.yml` GitHub Actions workflow publishes the content of these docs to github.io if the workflow itself and [GitHub Pages is enabled for your repository](https://docs.github.com/en/pages/quickstart).

Expand-Template.ps1

@@ -166,6 +166,12 @@ try {
         "(?m)^.*\[GitHub Actions status\].*`r?`n"=""
         "(?m)^.*\[codecov\].*`r?`n"=""
     }
+    Replace-Placeholders -Path "docfx/docfx.json" -Replacements @{
+        'Library'=$LibraryName
+    }
+    Replace-Placeholders -Path "docfx/docs/getting-started.md" -Replacements @{
+        'Library'=$LibraryName
+    }
 
     # Specially handle azure-pipelines .yml edits
     Replace-Placeholders -Path "azure-pipelines/build.yml" -Replacements @{

docfx/.gitignore

@@ -0,0 +1,2 @@
+_site/
+api/

docfx/docfx.json

@@ -0,0 +1,48 @@
+{
+	"metadata": [
+		{
+			"src": [
+				{
+					"src": "../src/Library",
+					"files": [
+						"**/*.csproj"
+					]
+				}
+			],
+			"dest": "api"
+		}
+	],
+	"build": {
+		"content": [
+			{
+				"files": [
+					"**/*.{md,yml}"
+				],
+				"exclude": [
+					"_site/**"
+				]
+			}
+		],
+		"resource": [
+			{
+				"files": [
+					"images/**"
+				]
+			}
+		],
+		"xref": [
+			"https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
+		],
+		"output": "_site",
+		"template": [
+			"default",
+			"modern"
+		],
+		"globalMetadata": {
+			"_appName": "Library",
+			"_appTitle": "Library",
+			"_enableSearch": true,
+			"pdf": false
+		}
+	}
+}

docfx/docs/features.md

@@ -0,0 +1,3 @@
+# Features
+
+TODO

docfx/docs/getting-started.md

@@ -0,0 +1,12 @@
+# Getting Started
+
+## Installation
+
+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)
+
+## Usage
+
+TODO

docfx/docs/toc.yml

@@ -0,0 +1,5 @@
+- name: Features
+  href: features.md
+- name: Getting Started
+  href: getting-started.md
+

docfx/index.md

@@ -0,0 +1,9 @@
+---
+_layout: landing
+---
+
+# Overview
+
+This is your docfx landing page.
+
+Click "Docs" across the top to get get started.

docfx/toc.yml

@@ -0,0 +1,4 @@
+- name: Docs
+  href: docs/
+- name: API
+  href: api/