Merge pull request #792 from dotnet/dev/andre/libtemplateUpdate

Merge latest Library.Template

.config/dotnet-tools.json

@@ -3,22 +3,32 @@
   "isRoot": true,
   "tools": {
     "powershell": {
-      "version": "7.4.5",
+      "version": "7.4.6",
       "commands": [
         "pwsh"
-      ]
+      ],
+      "rollForward": false
     },
     "dotnet-coverage": {
-      "version": "17.12.5",
+      "version": "17.12.6",
       "commands": [
         "dotnet-coverage"
-      ]
+      ],
+      "rollForward": false
     },
     "nbgv": {
-      "version": "3.6.143",
+      "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 docfx/docfx.json
+      name: 📚 Generate documentation
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docfx/_site
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.github/workflows/libtemplate-update.yml

@@ -0,0 +1,72 @@
+name: Library.Template update
+
+# PREREQUISITE: This workflow requires the repo to be configured to allow workflows to push commits and create pull requests.
+# Visit https://github.com/USER/REPO/settings/actions
+# Under "Workflow permissions", select "Read and write permissions" and check "Allow GitHub Actions to create ...pull requests"
+# Click Save.
+
+on:
+  schedule:
+  - cron: "0 3 * * Mon" # Sun @ 8 or 9 PM Mountain Time (depending on DST)
+  workflow_dispatch:
+
+jobs:
+  merge:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
+
+    - name: merge
+      shell: pwsh
+      run: |
+        $LibTemplateBranch = & ./azure-pipelines/Get-LibTemplateBasis.ps1 -ErrorIfNotRelated
+        if ($LASTEXITCODE -ne 0) {
+          exit $LASTEXITCODE
+        }
+
+        git fetch https://github.com/aarnott/Library.Template $LibTemplateBranch
+        if ($LASTEXITCODE -ne 0) {
+          exit $LASTEXITCODE
+        }
+        $LibTemplateCommit = git rev-parse FETCH_HEAD
+
+        if ((git rev-list FETCH_HEAD ^HEAD --count) -eq 0) {
+          Write-Host "There are no Library.Template updates to merge."
+          exit 0
+        }
+
+        git -c http.extraheader="AUTHORIZATION: bearer $env:GH_TOKEN" push origin -u FETCH_HEAD:refs/heads/auto/libtemplateUpdate
+    - name: pull request
+      shell: pwsh
+      run: |
+        # If there is already an active pull request, don't create a new one.
+        $existingPR = gh pr list -H auto/libtemplateUpdate --json url | ConvertFrom-Json
+        if ($existingPR) {
+          Write-Host "::warning::Skipping pull request creation because one already exists at $($existingPR[0].url)"
+          exit 0
+        }
+
+        $prTitle = "Merge latest Library.Template"
+        $prBody = "This merges the latest features and fixes from [Library.Template's  branch](https://github.com/AArnott/Library.Template/tree/).
+
+        <details>
+        <summary>Merge conflicts?</summary>
+        Resolve merge conflicts locally by carrying out these steps:
+
+        ```
+        git fetch
+        git checkout auto/libtemplateUpdate
+        git merge origin/main
+        # resolve conflicts
+        git commit
+        git push
+        ```
+        </details>
+
+        ⚠️ Do **not** squash this pull request when completing it. You must *merge* it."
+
+        gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle
+      env:
+        GH_TOKEN: ${{ github.token }}

CONTRIBUTING.md

@@ -36,3 +36,12 @@ The `nerdbank-streams` NPM package builds out of the `src/nerdbank-streams` dire
 Please review the [CONTRIBUTING.md](src/nerdbank-streams/CONTRIBUTING.md) document in that directory for instructions.
 
 [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).

Directory.Build.props

@@ -56,7 +56,7 @@
 
   <Target Name="PrepareReleaseNotes" BeforeTargets="GenerateNuspec" DependsOnTargets="GetBuildVersion">
     <PropertyGroup>
-      <PackageReleaseNotes Condition="'$(PackageProjectUrl)'!=''">$(PackageProjectUrl)/releases/tag/v$(Version)</PackageReleaseNotes>
+      <PackageReleaseNotes Condition="'$(RepositoryUrl)'!=''">$(RepositoryUrl)/releases/tag/v$(Version)</PackageReleaseNotes>
     </PropertyGroup>
   </Target>
 

Directory.Packages.props

@@ -37,7 +37,7 @@
   <ItemGroup>
     <GlobalPackageReference Include="CSharpIsNullAnalyzer" Version="0.1.593" />
     <GlobalPackageReference Include="DotNetAnalyzers.DocumentationAnalyzers" Version="1.0.0-beta.59" />
-    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.143" />
+    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.146" />
     <GlobalPackageReference Include="Nullable" Version="1.3.1" />
     <GlobalPackageReference Include="StyleCop.Analyzers.Unstable" Version="1.2.0.556" />
   </ItemGroup>

azure-pipelines/collect-artifacts.yml

@@ -37,7 +37,7 @@ steps:
   - powershell: |
       $ArtifactStagingFolder = & "azure-pipelines/Get-ArtifactsStagingDirectory.ps1"
       $CoverageResultsFolder = Join-Path $ArtifactStagingFolder "coverageResults-$(Agent.JobName)"
-      azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)Host,$(BuildConfiguration)"
+      azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)"
     displayName: 📢 Publish code coverage results to codecov.io
     timeoutInMinutes: 3
     continueOnError: true

azure-pipelines/dotnet.yml

@@ -6,7 +6,7 @@ parameters:
 
 steps:
 
-- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnaserror /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog"
+- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnAsError -warnNotAsError:NU1901,NU1902,NU1903,NU1904 /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog"
   displayName: 🛠 dotnet build
 
 - powershell: azure-pipelines/dotnet-test-cloud.ps1 -Configuration $(BuildConfiguration) -Agent $(Agent.JobName) -PublishResults

docfx/.gitignore

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

docfx/docfx.json

@@ -0,0 +1,48 @@
+{
+	"metadata": [
+		{
+			"src": [
+				{
+					"src": "../src/Nerdbank.Streams",
+					"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": "Nerdbank.Streams",
+			"_appTitle": "Nerdbank.Streams",
+			"_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/Nerdbank.Streams.svg)](https://nuget.org/packages/Nerdbank.Streams)
+
+## 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/